Cicode Reference

Ci Technologies Pty. Limited.

10-12 West Street

PO Box 174
PYMBLE NSW 2073
AUSTRALIA

Telephone: 61 2 9855 1000

Fax: 61 2 9488 9164
DISCLAIMER

Ci Technologies Pty. Limited 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, Ci Technologies Pty. Limited reserves the right to revise this publication at any time without incurring an
obligation to notify any person of the revision.

COPYRIGHT

© Copyright 2001 Ci Technologies Pty. Limited. All rights reserved.

TRADEMARKS

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

CITECT is a registered trademark of Ci Technologies Pty. Limited.

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

MS-DOS, Windows, Windows 95, Windows NT, Windows 98, Windows 2000, Windows for Workgroups, LAN Manager, Excel
and MSMAIL are trademarks of Microsoft Corporation.

DigiBoard, PC/Xi and Com/Xi are trademarks of DigiBoard.

Novell, Netware and Netware Lite are registered trademarks of Novell Inc.

dBASE is a trademark of Borland Inc.

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

July 2001 Edition for Citect Version 5.40

Manual Revision 5.40.
Automatically generated, printed and bound in Australia.
Citect Documentation
The documentation supplied with your Citect V5 software is provided in several formats to assist the many
requirements of our users.

Other sources that will assist you to learn about your Citect system:

Getting Started An installation guide and product overview for new V5 users.

User's Guide A reference for the design and development of your Citect system.

Cicode Reference A reference for writing and debugging Cicode.

CitectVBA Reference A reference for writing and debugging CitectVBA.

Online Help The online information provided with Citect includes all the
material included in the printed manuals. This information is
regularly updated.

Example Project Use the Example Project for ideas for your own project.

Knowledge Base Provides high level technical information beyond the scope of the
online and printed materials.

Technical Overview A concise discussion of Citect’s technical capabilities.

Online Help Glossary Over 180 technical terms and concepts defined.

Technical Support Check the Introduction of the Citect User's Guide for more
information.
 Contents

Part A Using Cicode 1

Chapter 1 - Introduction to Cicode..................................................................................... 3

Introduction to Cicode.................................................................................................................. 3
Using Cicode Files....................................................................................................................... 4
Using Cicode Commands ............................................................................................................ 4
Setting Variables.................................................................................................................... 5
Copying Variables .................................................................................................................. 5
Performing Calculations with Variables ................................................................................. 6
Using Multiple Command Statements.................................................................................... 6
Getting Operator Input ........................................................................................................... 6
Using Cicode Expressions........................................................................................................... 8
Displaying Data with Expressions .......................................................................................... 8
Decision Making with Expressions......................................................................................... 8
Logging Expression Data ....................................................................................................... 9
Using Expressions to Trigger Events ..................................................................................... 9
Using Cicode Functions............................................................................................................. 10
Calling Functions from Commands and Expressions .......................................................... 10
Performing Functions........................................................................................................... 10
Evaluating Functions............................................................................................................ 11
Combining Functions with Other Statements....................................................................... 11
Passing Data to Functions (Arguments) .............................................................................. 11
Using String Arguments ....................................................................................................... 12
Using the Caret ( ^ ) escape sequence character................................................................ 12
Using Multiple Arguments .................................................................................................... 13
Using Numeric Arguments ................................................................................................... 14
Using Variable Arguments ................................................................................................... 14
Using Operator Input............................................................................................................ 14
Returning Data From Functions........................................................................................... 14
Commonly Used Functions ....................................................................................................... 15
Using Alarm Functions......................................................................................................... 15
Using Page Functions.......................................................................................................... 16
Using Keyboard Functions................................................................................................... 16
Using Report Functions ....................................................................................................... 17
Using Time/Date Functions.................................................................................................. 17
Using Miscellaneous Functions ........................................................................................... 17
Chapter 2 - Writing Functions .......................................................................................... 19
Writing Functions....................................................................................................................... 19
vi Contents

Function Structure ................................................................................................................19

Writing Groups of Functions .................................................................................................21
Cicode Function Libraries .....................................................................................................21
Creating a Function Outline ..................................................................................................21
Using File and Function Headers .........................................................................................22
Using Comments in Cicode ..................................................................................................23
Using Comments for Debugging Functions ..........................................................................24
Following Cicode Syntax ......................................................................................................24
Cicode Function Syntax .............................................................................................................26
Function Scope.....................................................................................................................27
Declaring the Return Data Type ...........................................................................................28
Declaring Functions ..............................................................................................................29
Naming Functions.................................................................................................................30
Function Argument Structure................................................................................................31
Declaring Argument Data Type ............................................................................................33
Naming Arguments ...............................................................................................................34
Setting Default Values for Arguments...................................................................................35
Returning Values from Functions .........................................................................................37
Chapter 3 - Variables .........................................................................................................39
Declaring Variable Properties ...............................................................................................39
Declaring the Data Type .......................................................................................................39
Naming Variables .................................................................................................................40
Setting Default Variable Values ............................................................................................40
Using Variable Scope ...........................................................................................................40
Using Database Variables ....................................................................................................42
Using Arrays...............................................................................................................................42
Declaring Array Properties....................................................................................................43
Declaring the Array Data Type .............................................................................................43
Naming Arrays ......................................................................................................................43
Declaring the Array Size .......................................................................................................43
Setting default (initial) Array values ......................................................................................44
Passing Array Elements as Function Arguments .................................................................44
Using One-Dimensional Arrays ............................................................................................45
Using Two-Dimensional Arrays ............................................................................................45
Using Three-Dimensional Arrays..........................................................................................45
Using Arrays in Functions.....................................................................................................46
Using Array elements in Loops.............................................................................................46
Using the Table (Array) Functions ........................................................................................46
Converting and Formatting Variables.........................................................................................46
Converting Integers to Strings ..............................................................................................47
Converting Real Numbers to Strings ....................................................................................47
Converting Strings to Integers ..............................................................................................48
Converting Strings to Real Numbers ....................................................................................48
Formatting Text Strings in Cicode ........................................................................................48
Escape Sequences (string formatting commands)...............................................................50
Chapter 4 - Operators ........................................................................................................51
Using Data Operators.................................................................................................................51
 Contents vii

Using Mathematical Operators............................................................................................. 51

Using Bit Operators.............................................................................................................. 53
Using Relational Operators.................................................................................................. 53
Using Logical Operators ...................................................................................................... 54
Order of Precedence of Operators....................................................................................... 56
Chapter 5 - Conditional Executors ................................................................................... 57
Using Conditional Executors...................................................................................................... 57
Setting IF ... THEN Conditions ............................................................................................. 57
Using FOR ... DO Loops ...................................................................................................... 58
Using WHILE ... DO Conditional Loops ............................................................................... 59
Nested Loops....................................................................................................................... 59
Using the SELECT CASE statement ................................................................................... 60
Chapter 6 - Advanced Cicode Tasks ................................................................................ 63
Handling Events ................................................................................................................... 63
How Citect Executes ............................................................................................................ 63
Multitasking .......................................................................................................................... 64
Foreground and Background Tasks..................................................................................... 64
Controlling Tasks ................................................................................................................. 65
Pre-emptive Multitasking...................................................................................................... 65
Chapter 7 - Editing and Debugging Cicode ..................................................................... 67
The Cicode Editor ...................................................................................................................... 67
Starting the Cicode Editor .................................................................................................... 68
Changing the default Cicode Editor ..................................................................................... 69
Creating Cicode files............................................................................................................ 70
Creating Cicode functions.................................................................................................... 70
Saving Cicode files .............................................................................................................. 71
Opening existing Cicode files............................................................................................... 72
Deleting Cicode files ............................................................................................................ 73
Finding text within Cicode files............................................................................................. 73
Compiling Cicode files ......................................................................................................... 73
Viewing Cicode compile errors ............................................................................................ 74
Cicode Editor Options................................................................................................................ 74
Docking Editor Windows and Toolbars ................................................................................ 74
How to view/hide the Editor Options Properties Dialog........................................................ 75
Cicode Editor Options – Windows and Bars tab .................................................................. 76
Cicode Editor Options – (View) Windows and Toolbars ...................................................... 76
Cicode Editor - Toolbar Options........................................................................................... 76
Cicode Editor - Window Options .......................................................................................... 77
Cicode Editor Options – Option Properties tab .................................................................... 83
Cicode Editor Options – Language Formatter Properties tab .............................................. 85
Debugging Cicode ..................................................................................................................... 86
How to switch to debug mode .............................................................................................. 86
How to debug a function ...................................................................................................... 86
How to remotely debug a function........................................................................................ 87
Debugging - Using Breakpoints ........................................................................................... 88
How to insert/remove a breakpoint ...................................................................................... 89
How to enable/disable a breakpoint..................................................................................... 89
viii Contents

Debugging - Stepping through the Code ..............................................................................90

Chapter 8 - Cicode Programming Standard ....................................................................91
Cicode Programming Standard ..................................................................................................91
Variable Declaration Standards..................................................................................................91
Variable Scope Standards..........................................................................................................92
Variable Naming Standards .......................................................................................................92
Standards for Constants, Variable Tags, and Labels.................................................................93
Formatting Simple Declarations .................................................................................................94
Formatting Executable Statements ............................................................................................95
Formatting Expressions..............................................................................................................96
Comments ..................................................................................................................................96
Formatting Functions .................................................................................................................97
[Scope] .................................................................................................................................97
[Type]....................................................................................................................................97
Keyword................................................................................................................................97
Name ....................................................................................................................................97
Argument(s) ..........................................................................................................................97
Statement(s) .........................................................................................................................97
Keyword................................................................................................................................97
Function Naming Standards .................................................................................................98
Source File Headers .............................................................................................................99
Function Headers ...............................................................................................................100
Modular Programming..............................................................................................................101
Cohesion ............................................................................................................................102
Coupling .............................................................................................................................103
Cohesion and Coupling Examples......................................................................................104
Defensive Programming...........................................................................................................106
Error handling...........................................................................................................................107
Debug Error Trapping...............................................................................................................109
The DebugMsg Function ....................................................................................................109
The Assert Function............................................................................................................110
Part B Function Categories 113

Chapter 9 - Function Categories ..................................................................................... 115

ActiveX Functions.....................................................................................................................115
Alarm Functions .......................................................................................................................115
Clipboard Functions .................................................................................................................117
Cluster Functions .....................................................................................................................117
Colour Functions ......................................................................................................................117
Communication Functions........................................................................................................117
DDE Functions .........................................................................................................................118
Device Functions......................................................................................................................119
Display Functions .....................................................................................................................120
DLL Functions ..........................................................................................................................123
Error Functions.........................................................................................................................123
Event Functions........................................................................................................................123
 Contents ix

File Functions .......................................................................................................................... 124

Form Functions........................................................................................................................ 125
Format Functions..................................................................................................................... 126
FTP Functions ......................................................................................................................... 126
FuzzyTech Functions............................................................................................................... 126
Super Genie Functions ............................................................................................................ 127
Group Functions ...................................................................................................................... 128
I/O Device Functions ............................................................................................................... 128
Keyboard Functions................................................................................................................. 129
Mail Functions ......................................................................................................................... 129
Math/Trig Functions ................................................................................................................. 130
Miscellaneous Functions ......................................................................................................... 131
Page Functions........................................................................................................................ 132
Plot Functions.......................................................................................................................... 133
Report Functions ..................................................................................................................... 133
Security Functions ................................................................................................................... 134
SPC Functions......................................................................................................................... 134
SQL Functions ......................................................................................................................... 135
String Functions....................................................................................................................... 136
Table (Array) Functions ........................................................................................................... 137
Task Functions ........................................................................................................................ 137
Time/Date Functions ............................................................................................................... 138
Trend Functions....................................................................................................................... 139
Window Functions ................................................................................................................... 141
Part C Functions Reference 143

Part D Cicode Errors 665

Cicode and General Errors ................................................................................................ 668

Index................................................................................................................................. 681
 1

Part A
Using Cicode
 Chapter 1 - Introduction to Cicode

Introduction to Cicode

Cicode is a simple, easy-to-use computer programming language designed for use in Citect to monitor
and control plant equipment. It is a structured language similar to Visual Basic or 'C', however with
the aid of this help, you need no previous programming experience to use it.
Using Cicode, you have access to all real-time data (variables) in the Citect project, and all Citect
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.

Quick Start
The following sections should be used as a quick start to using Cicode in your Citect projects:
Cicode can be stored in procedures called functions for multiple reuse and centralised maintenance.
For more details, see the section titled 'Using Cicode Files'.
Cicode can be typed directly into command fields in online Citect forms. For details, see the section
titled '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 the section titled '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
Citect 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 'Commonly Used Functions'.
Where system functionality cannot be achieved with in-built functions, you can write your own
functions. See the section titled 'Writing Functions'.
The Cicode Editor is the code editing tool provided with Citect for the writing, editing and debugging
of your Cicode code. For details, see the section titled 'The Cicode Editor'.
4 Using Cicode Files

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 minimise potential future problems with maintaining your Cicode files, you should adopt a
programming standard as early as possible, and as discussed in the section 'Cicode Programming
Standard'. Be sure to maintain structured Cicode files, by logically grouping your Cicode functions
within the files, and by choosing helpful descriptive names. Modular programming methods are
discussed in the section titled 'Modular Programming'. Cicode functions are introduced in the section
titled 'Cicode Functions'. Debugging Cicode is discussed in the section titled 'Debugging Cicode'.
When you compile your Citect 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. There is no
limit to the number of Cicode files you can use. Cicode files reside in the same directory as your
Citect project. When you back up your project, all Cicode source files in the project directory are also
backed up.

Using Cicode Commands

Cicode commands extend the control element of a Citect control and monitoring system. You use
commands to control your Citect 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 wish 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.
 Chapter 1 - Introduction to Cicode 5

Setting Variables

You can set a Variable in Citect 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,
Val is the value being assigned to the variable.

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;

Copying Variables

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.
6 Using Cicode Commands

Performing Calculations with Variables

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 Citect 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.
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: You must separate each statement in a command with a semi-colon (;) or Citect does not
recognise the end of a statement, and an error 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, you should not 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.

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

 Chapter 1 - Introduction to Cicode 7

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

Key Sequence F2 ### Enter

Command B1_TIC_101_SP = Arg1;
...is passed to the command
as Arg1

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:

F2 1 2 3 Enter

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

F2 1 2 3 , 1 8 Enter

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

Displaying Data with 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.

Decision Making with Expressions

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.
 Chapter 1 - Introduction to Cicode 9

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.

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.

Using Expressions to Trigger Events

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
10 Using Cicode Expressions

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

Using Cicode Functions

A Cicode function can perform more complex tasks than a simple command or expression allows.
Functions give you access to Citect graphics pages, alarms, trend data, and so on.
Citect 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.

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

Performing Functions
In the following command, the PageNext()function displays the next graphics page when the
Page Down keyboard key is pressed.

Key Sequence Page_Down

Command PageNext();
 Chapter 1 - Introduction to Cicode 11

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"

OFF Text "No Alarms Active"

NOTES: 1. 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.
2. You must use the parentheses () in the function name, even if the function uses no
arguments.
3. 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:

Command Report("Shift"); B1_TIC_101_PV = 10;

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 very 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.
12 Using Cicode Functions

NOTE: Some functions (such as PageNext()) do not require any arguments. However you must
include the parentheses ( ) or Citect will not recognise 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.
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
 Chapter 1 - Introduction to Cicode 13

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' for the list of escape
sequences used in Cicode.
In the following Cicode example, both of these message functions will display the following message.

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.
14 Using Cicode Functions

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.

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

Using Operator Input

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:

F10 D E S P A T C H Enter

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.
 Chapter 1 - Introduction to Cicode 15

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.

Commonly Used Functions

Cicode has many functions that perform a variety of tasks. Many of these are used for building
complex Citect systems. The functions you will most often use are divided into six categories:

Alarm functions – see the section titled 'Using Alarm Functions'

Page functions – see the section titled 'Using Page Functions'

Keyboard functions – see the section titled 'Using Keyboard Functions'

Report functions – see the section titled 'Using Report Functions'

Time/date functions – see the section titled 'Using Time/Date Functions'

Miscellaneous functions – see the section titled 'Using Miscellaneous Functions'

Using 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
16 Commonly Used Functions

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

Using Page Functions

With the page functions, you can display your graphics pages and the standard alarm pages.
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(Page) 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(Name) Displays a file on the file page configured in the project.
PageGoto(Page) 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.

Using Keyboard Functions

Keyboard functions control the processing of keyboard entries and the movement of the keyboard
cursor on the graphics page.
 Chapter 1 - Introduction to Cicode 17

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

Using Report Functions

To run a report by operator action, use the following function:
Report(Name) Runs the report on the report server.

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

Using Miscellaneous Functions

Beep()Beeps the speaker on the Citect 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(Name, Password) Allows a user access to the Citect system.
LoginForm()Displays a dialog box to allow a user to log in to the system.
Logout()Logs the current user out of the Citect system.
Name()Returns the user name of the user who is currently logged in to the system.
Prompt(String) Displays a message on the screen. The message String is supplied as an argument
to the function.
Shutdown()Terminates Citect. 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 Citect system.
 Chapter 2 - Writing Functions

Writing Functions
Citect 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.

Function Structure

A function in Cicode can be described as a collection or list of sequential statements that Citect 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 Citect. This name is referred to when the function is called upon
20 Writing Functions

(called) to be executed (perform the statements it contains) by some other event, action, or function in
Citect.

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 a pair of curved brackets ( ) 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 located between the function name line and the END statement line, contain the
statements that will be executed when the function is called in Citect. These statements will be
executed one at a time in logical order from top to bottom within the function. For details about
function structure, see the section titled 'Formatting Functions'. For details about Cicode function
syntax, see the section titled 'Following Cicode Syntax'.
For details about using comments in Cicode and in Cicode Functions, see the section titled '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:

Command IF COUNTER < 100 THEN COUNTER =

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
 Chapter 2 - Writing Functions 21

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 typed once. It can then be called any number of
times, from anywhere in Citect that requires this functionality. Because the code exists in the one
location, rather than repeated wherever needed (in potentially very 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.
22 Writing Functions

This file has 4 functions. The master function calls the other
functions.

ChangeAnalogAlarmThresholds ( )
This calls in turn:

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.

Using File and Function Headers

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: FJ Smith
**
** DATE: March 1996
**
** REVISION: 1.0 for Citect v5.0
**
** This file contains functions to allow the operator to load the
** recipe data from the SQL server to the PLC.
*/
 Chapter 2 - Writing Functions 23

Following the file header are the functions in series:

/*
** Main function
*/
FUNCTION
RecipeDownload ( )
! {body of function}
! .
END

/*
** Function to open the SQL connection.
*/
FUNCTION
RecipeConnectSQL ( )
! {body of function}
! .
END

! (and so on)

Using Comments in Cicode

It is good programming practice to include comments in all your Cicode files. Comments allow you to
quickly understand how a function works next time you (or another designer) need to modify it.
The Cicode compiler recognises the following single line, C style, and C++ style comments:

! A single line comment

WHILE DevNext ( hDev ) DO
Counter = Counter + 1 ; ! An in-line comment
END

/* A block comment is a C-style comment, and can

extend over several lines. Block comments must
finish with a delimiter, but delimiters at the
start of each line are optional only. */

// A double-slash comment is a C++ style comment, for example:

Variable = 42; // This is a comment
Single line ( ! ) and C++ style ( // ) comments can have a line of their own, where they refer to the
block of statements either before or after it. (You should set a convention for these comments.) These
comments can also be on the same line as a statement, to explain that statement only. All characters
after the ! or // (until the end of the line) are ignored by the compiler.
24 Writing Functions

Block (C style) comments begin with /* and end with */. These C style comments need no punctuation
between the delimiters.

Using Comments for Debugging Functions

You can use comments to help with the debugging of your functions. You can use comments to
temporarily have the compiler ignore blocks of statements by changing them to comments. C style and
C++ style comments can be nested, for example.

FUNCTION
IncCounter ( )
IF COUNTER < 100 THEN
COUNTER = COUNTER + 1 ;
/* ELSE // Comment about statement
COUNTER = 0; // Another comment
*/
END
END

The complete ELSE condition of the IF conditional executor will be ignored (and not execute) so long
as the block comment markers are used in this example.

NOTE: The inline ( // ) comments have no effect within the block ( /* and */ ) comments (as the
whole section is now one big comment), and should remain unchanged, so that when you do
remove the block comments, the inline comments will become effective again.

Following Cicode Syntax

Some programming languages have strict rules about how the code must be formatted, including the
indenting and positioning of the code structure. Cicode has no indenting or positioning requirements,
allowing you to design your own format - provided only that you follow the correct syntax order for
each statement. However, it is always a good idea to be consistent with your programming structure
and layout, so that it can be easily read and understood.
For more information about programming standards, see the section titled 'Cicode Programming
Standard', which includes sections on:

standards for constants, variable tags, and labels

standards variables: declaration, scope, and naming

standards for functions: naming , file headers, headers

formatting of: declarations, statements, expressions, and functions

use of comments
For information on problem solving, see the sections titled 'Modular Programming', 'Defensive
Programming', 'Error handling', or 'Debugging Cicode'.
 Chapter 2 - Writing Functions 25

The following is an example of a simple Cicode function:

/*
This function is called from a keyboard command. The operator
presses the key and enters the name of the page to be displayed.
If the page cannot be displayed, an error message is displayed at
the prompt AN.
*/

INT
FUNCTION
MyPageDisplay ( STRING sPage ) ! pass in the name of the page to be
displayed

! declare a local integer to hold the results of the

pagedisplay function
INT Status;

! call the page Cicode pagedisplay function and store the

result
Status = PageDisplay ( sPage ) ;

! determine if the page display was successful

IF Status < > 0 THEN ! failed

! display an error message at the prompt AN

DspError ( "Cannot Display " + sPage ) ;
END

! return the status to the caller

RETURN Status;
END

The rules for formatting statements in Cicode functions are simple, and ensure that the functions
compile without error.
You should use white space to make your code more readable. In the example above, all code
between the FUNCTION and END statements is indented, and the statement within the IF THEN
conditional executor is further indented to make the conditions and actions clear. You should develop
a pattern of indentation - and stick to it. Extra blank lines in the code make it easier to read (and
understand).
26 Cicode Function Syntax

Cicode Function Syntax

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.
Also, statements shown between square brackets ( [ ] ) are optional. The square brackets
should not be included in the statement, and are shown here only for your information.

Cicode functions have the following syntax:

[ <Scope> ]
[ <ReturnDataType> ]
FUNCTION
<FunctionName> ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
RETURN <ReturnValue> ;
END
Where:
<Scope> = Scope Statement:
optional, PRIVATE or PUBLIC, default PUBLIC, no semicolon.
See the section titled 'Function Scope'.
<ReturnDataType> = Return Data Type Statement:
optional, INT or REAL or STRING or OBJECT, no default, no semicolon.
See the section titled 'Declaring the Return Data Type'.
FUNCTION = FUNCTION Statement:
required, indicates the start of the function, keyword, no semicolon.
See the section titled 'Declaring Functions'.
<FunctionName> = Name statement:
required, up to 32 ASCII text characters, case insensitive, no spaces, no reserved words, no
default, no semicolon.
See the section titled 'Naming Functions'.
( <Arguments> ) = Argument statement:
surrounding brackets required even if no arguments used, if more than one argument - each must
be separated by a comma, can contain constants or variables of INT or REAL or STRING data
type, default can be defined in declaration, can be spread over several lines to aid readability, no
semicolon.
See the section titled 'Function Argument Structure'.
 Chapter 2 - Writing Functions 27

<Statement> = Executable Statement:

required, one or more executable statements that perform some action in Citect, often used
to manipulate data passed into the function as arguments, semicolon required.
RETURN = RETURN Statement:
optional, used to instruct Cicode to return a value to the caller of the function – usually a
manipulated result using the arguments passed in to the function by the caller, must be followed
by Return Value Statement, keyword, no semicolon.
See the section titled 'Returning Values From Functions'.
<ReturnValue> = Return Value Statement;
required if RETURN Statement used in function, must be either a constant or a variable, the data
type must have been previously declared in the function Return Data Type Statement – or does
not return a value, semicolon required.
See the section titled 'Returning Values From Functions'.
END = END Statement:
required, indicates the end of the function, keyword, no semicolon.
See section titled 'Declaring Functions'.

End of Line markers

Most statements within the function are separated by semicolons ( ; ) but some exceptions exist. The
FUNCTION and END Statements (the start and end of the function) have no semicolons, nor does the
Scope or Return Data Type Statements, nor any statement that ends with a reserved word..
Where a statement is split over several lines (for example, within the IF THEN conditional executor),
each line ends with a semicolon - unless it ends in a reserved word.

Function Scope

The optional Scope Statement of a function (if used), precedes all other statements of a function
declaration in Cicode, including the FUNCTION Statement.
The scope of a function can be either PRIVATE or PUBLIC, and is declared public by default. That
is, if no Scope Statement is declared, the function will have public scope.
Both PRIVATE and PUBLIC are Cicode keywords and as such, are reserved.
A private scope function is only accessible (can be called) within the file in which it is declared.
Public scope functions can be shared across Cicode files, and can be called from pages and Citect
databases (e.g. Alarm.dbf).
Because functions are public by default, to make a function public requires no specific declaration. To
make a function private however, you must prefix the FUNCTION Statement with the word
PRIVATE.
28 Cicode Function Syntax

PRIVATE
FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
END

Declaring the Return Data Type

For information about the RETURN Statement, see the section titled 'Returning Values from
Functions'.
The optional Return Data Type Statement of a function (if used), follows the optional Scope Statement
(if used), and precedes the FUNCTION Statement declaration in Cicode.
The return data type of a function can be only one of four possible data types: INT (32 bits), REAL
(32 bits), STRING (255 bytes), or OBJECT (32 bits). If no Return Data Type Statement is declared,
the function will not be able to return any type of data.
INT, REAL, STRING, and OBJECT are Cicode keywords and as such, are reserved.

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.

To declare the data type that will be returned to the calling code, you must prefix the FUNCTION
Statement with one of the Cicode data type keywords, in the <ReturnDataType> placeholder in the
following example.

<ReturnDataType>
FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
END
 Chapter 2 - Writing Functions 29

The following example returns an integer of value 5:

INT
FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
INT Status = 5;
<Statement> ;
RETURN Status;
END

If the RETURN Statement within the function encounters a different data type to that declared in the
Return Data Type Statement, the value is converted to the declared return data type.
In the example below, the variable Status is declared as a real number within the function. However,
Status is converted to an integer when it is returned to the caller, because the data type of the return
was declared as an integer type in the Return Data Type Statement:

INT ! declare return value as integer

FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
REAL Status = 5; ! declare variable as a REAL number
<Statement> ;
RETURN Status; ! returned as an integer number
END

NOTE: If you do not specify a return data type, the function does not return a value.

Declaring Functions

The required FUNCTION Statement follows the optional Scope Statement (if used) and the optional
Return Data Type Statement (if used), and precedes all other statements of a function declaration in
Cicode. Everything between it and the END Statement, contains the function.
Both FUNCTION and END are Cicode keywords and as such, are reserved.
You declare the start of a function with the FUNCTION Statement, and declare the end of a function
with the END Statement:

FUNCTION
<FunctionName> ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
END
30 Cicode Function Syntax

The FUNCTION Statement must be followed by the Name Statement, then the Argument Statement,
before any code statements that will be processed by the function.
For information on the Name and Argument Statements, see the sections titled 'Naming Functions' and
'Function Argument Structure'.
For information on calling functions, see the section titled 'Function Structure'.
All code (as represented by the <Statement> placeholders) located between the FUNCTION and
END Statements, will be executed (processed by the function) when called to do so.
Functions can execute a large variety of statements, and are commonly used to process and manipulate
data, including the arguments passed when the function was called, plant-floor and other Citect data,
Windows data, and so on. Citect provides many pre-built functions. For more information, see the
section titled 'Commonly Used Functions'.

Naming Functions

The required Name Statement follows the FUNCTION Statement and precedes the Arguments
Statement in a Citect function. The function name is used elsewhere in Citect to activate (call) the
function to have it perform the statements it contains.
Replace the <FunctionName> placeholder in the following function example with an appropriate
name for your function. See the section titled 'Function Naming Standards' for details.

FUNCTION
<FunctionName> ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
END
You can use up to 32 ASCII text characters to name your functions. You can use any valid name
except for a reserved word. The case is not important to the Citect compiler, so you can use upper and
lower case to make your names clear. For example, MixerRoomPageDisplay is easier to read than
mixerroompagedisplay or MIXERROOMPAGEDISPLAY.

FUNCTION
MixerRoomPageDisplay ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
END
Your functions take precedence over any other entity in Citect with the same name:

Variable Tags. When you call a function by the same name as a variable tag, the function has
precedence. The variable tag can never be referred to because the function executes each time the
name is used.
 Chapter 2 - Writing Functions 31

Pre-built Functions. You can give your function the same name as any pre-built Cicode function.
Your function takes precedence over the pre-built function - the pre-built function cannot be called.
Because pre-built Cicode functions cannot be changed, this provides a method of 'modifying' any
pre-built function to suit an application. For example, you might want to display the message
"Press F1 for Help" whenever you display a page. You could simply write a new function called
PageDisplay ( ). The body of the function would be the statements that display the page and
prompt message:

PageDisplay ( <Arguments> ) ;
Prompt ( "Press F1 for Help" ) ;

NOTE: Your function is invoked whenever you use the function name in Citect.

Function Argument Structure

The optional Arguments Statement follows the required FUNCTION Statement and precedes the
executable statements of a function in Cicode.
When you call a function, you can pass one or more arguments to the function, enclosed within the
parentheses ( ) located after the function name statement. Replace the <Arguments> placeholder in
the following function example with your Argument Statement.

FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
END
For your function to perform tasks with data, it requires accessibility to the data. One way to achieve
this, is to pass the data directly to the function when the function is being called. To enable this
facility, Cicode utilises arguments in its function structure. An argument in Cicode is simply a variable
that exists in memory only as long as its function is processing data, so the scope of an argument is
limited to be local only to the function. Arguments cannot be arrays.
Arguments are variables that are processed within the body of the function only. You cannot use an
argument outside of the function that declares it.
As arguments are variables used solely within functions, they must be declared just as you would
otherwise declare a variable in Cicode. See the section titled 'Declaring Variable Properties'. An
argument declaration requires a data type, a unique name, and may contain an initial value which also
behaves as the default value for the argument.
32 Cicode Function Syntax

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.
Also, Statements shown between square brackets ( [ ] ) are optional. The square brackets
should not be included in the statement, and are shown here only for your information.

Cicode function argument statements have the following syntax:

<ArgumentDataType>
<ArgumentName>
[ = <InitialDefaultValue> ]

where:
<ArgumentDataType> = Argument Data Type Statement:
required, INT or REAL or STRING.
See the section titled 'Declaring Argument type'.
<ArgumentName> = Argument Name Statement:
required, up to 32 ASCII text characters, case insensitive, no spaces, no reserved words.
See the section titled 'Naming Arguments'.
<InitialDefaultValue> = Argument Initialisation Statement:
optional, preceded by equals ( = ) assignment operator, a value to assign to the argument variable
when first initialised, must be the same data type as that declared in the argument
<ArgumentDataType> parameter, defaults to this value if no value passed in for this argument
when the function was called.
See the section titled 'Setting Default Values for Arguments'.

The Argument Statement in a Cicode function must have only one set of surrounding parentheses ( )
brackets, even if no arguments are declared in the function.
If more than one argument is used in the function, each must also be separated by a comma.
Argument Statements can be separated over several lines to aid in their readability.
When you call a function, the arguments you pass to it are used within the function to produce a
resultant action or return a value. For information on passing data to functions, see the section titled
'Passing Data to Functions'. For information on returning results from functions, see the section titled
'Returning Data From Functions'.
 Chapter 2 - Writing Functions 33

Arguments are used in the function and referred to by their names. For instance, if we name a function
AddTwoIntegers, and declare two integers as arguments naming them FirstInteger and
SecondInteger respectively, we would end up with a sample function that looks like the following:

INT
FUNCTION
AddTwoIntegers ( INT FirstInteger, INT SecondInteger )
INT Solution ;
Solution = FirstInteger + SecondInteger ;
RETURN Solution ;
END
In this example, the function would accept any two integer values as its arguments, add them together,
and return them to the caller as one integer value equal to the summed total of the arguments values
passed into the function.
This functionality of passing values into a function as arguments, manipulating the values in some way,
then being able to return the resultant value, is what makes functions potentially very powerful and
time saving. The code only needs to written once in the function, and can be utilised any number of
times from any number of locations in Citect. Write once, use many.

Declaring Argument Data Type

If an argument is listed in a Cicode function declaration, the Argument Data Type Statement is
required, and is listed first before the required Argument Name Statement and the optional Argument
Initialisation Statement.
The argument data type of a function can be only one of four possible data types: INT (32 bits),
REAL (32 bits), STRING (255 bytes), or OBJECT (32 bits).
INT, REAL, STRING, and OBJECT are Cicode keywords and as such, are reserved.

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.
Also, statements shown between square brackets ( [ ] ) are optional. The square brackets
should not be included in the statement, and are shown here only for your information.
34 Cicode Function Syntax

To declare the argument data type that will be used in the function, you must prefix the Argument
Name Statement with one of the Cicode data type keywords, in the <ArgumentDataType>
placeholder in the following example.

FUNCTION
FunctionName ( <ArgumentDataType> <ArgumentName> [ =
<InitialDefaultValue> ] )
<Statement> ;
<Statement> ;
<Statement> ;
END

The Argument Statement in a Cicode function must have only one set of surrounding parentheses ( )
brackets, even if no arguments are declared in the function.
If more than one argument is used in the function, each must also be separated by a comma.
Argument Statements can be separated over several lines to aid in their readability.

Naming Arguments

If an argument is listed in a Cicode function declaration, the Argument Name Statement is required,
and is listed second, after the required Argument Data Type Statement, and before the optional
Argument Initialisation Statement.
The argument name is used only within the function to refer to the argument value that was passed into
the function when the function was called. The name of the argument variable should be used in the
executable statements of the function in every place where you want the argument variable to be used
by the statement.

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.
Also, statements shown between square brackets ( [ ] ) are optional. The square brackets
should not be included in the statement, and are shown here only for your information.

Replace the <ArgumentName> placeholder in the following function example with an appropriate
name for your Argument variable. See the section titled 'Function Naming Standards' for details.
FUNCTION
FunctionName ( <ArgumentDataType> <ArgumentName> [ =
<InitialDefaultValue> ] )
<Statement> ;
<Statement> ;
<Statement> ;
END
 Chapter 2 - Writing Functions 35

You can use up to 32 ASCII text characters to name your arguments. You can use any valid name
except for a reserved word. The case is not important to the Citect compiler, so you can use upper and
lower case to make your names clear. For example, iPacketQnty is easier to read than ipacketqnty or
IPACKETQNTY .

FUNCTION
FunctionName ( INT iPacketQnty )
<Statement> ;
<Statement> ;
<Statement> ;
END
To refer to the argument (in the body of your function) you use the name of the argument in an
executable statement:

INT
FUNCTION
AddTwoIntegers ( INT FirstInteger, INT SecondInteger )
INT Solution ;
Solution = FirstInteger + SecondInteger ;
RETURN Solution ;
END

Setting Default Values for Arguments

If an argument is listed in a Cicode function declaration, the Argument Initialisation Statement is

optional, and if used, is listed last in the Argument Statement after the required Argument Data Type
and the Argument Name Statements. The Argument Initialisation Statement must be preceded by an
equals ( = ) assignment operator.

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.
Also, statements shown between square brackets ( [ ] ) are optional. The square brackets
should not be included in the statement, and are shown here only for your information.
36 Cicode Function Syntax

Replace the <InitialDefaultValue> placeholder in the following function example with an appropriate
value for your Argument variable.

FUNCTION
FunctionName ( <ArgumentDataType> <ArgumentName> [ =
<InitialDefaultValue> ] )
<Statement> ;
<Statement> ;
<Statement> ;
END
The default value for an argument must be of the same data type as declared for the argument in the
Argument Data Type Statement.
You assign a default argument variable value in the same manner that you assign a Cicode variable
value, by using the equals ( = ) assignment operator. For example:

FUNCTION
PlotProduct ( INT iPackets = 200 , STRING sName = "Packets" )
<Statement> ;
<Statement> ;
<Statement> ;
END

If you assign a default value for an argument, you do not have to pass a value for that argument when
you call the function, (because the function will use the default value from the declaration.) To pass an
empty argument to a function, omit any value for the argument in the call. For example, to call the
PlotProduct function declared in the previous example, and accept the default string value of
"Packets", a Cicode function call would look like:

PlotProduct ( 500 , )
Notice that the second argument for the function was omitted from the calling code. In this instance,
the default value for the second argument ( "Packets" ) would remain unchanged, and so would be
used as the second argument value in this particular function call.
If you do call that function and pass in a value for that argument in the call, the default value is
replaced by the argument value being passed in. However, the arguments are reinitialised every time
the function is called, so each subsequent call to the function will restore the default values originally
declared in the function.
If more than one argument is used in a function, each must also be separated by a comma. Equally, if
a function containing more than one argument is called, each argument must be accounted for by the
caller. In this case, if an argument value is to be omitted from the call, (to utilise the default value),
comma placeholders must be used appropriately in the call to represent the proper order of the
arguments.
For more information on function calls, callers, and calling, see the section titled 'Calling Functions
from Commands and Expressions'.
 Chapter 2 - Writing Functions 37

Argument Statements can be separated over several lines to aid in their readability.

Returning Values from Functions

Most pre-built Cicode functions supplied with Citect return a data value to their calling statement.
Mathematical functions return a calculated value. The Date ( ) and Time ( ) functions return the
current date and time. Other functions, like PageDisplay ( ), perform an action, and return the success
or failure status of the action as the return value.
You can also use return values in your own functions, to return data to the calling statement. The
return value is assigned in the RETURN Statement:
The optional RETURN Statement of a function (if used), must be placed in the executable Statements
section of a Cicode function between the FUNCTION and END Statements. Because the RETURN
Statement is used to return data values that have usually been manipulated by the function, they are
usually placed last just before the END Statement.

<ReturnDataType>
FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
<Statement> ;
<Statement> ;
RETURN <ReturnValue> ;
END
The RETURN Statement consists of the RETURN keyword followed by a value to be returned and
finished with the semicolon ( ; ) end-of-line marker.
The RETURN value must be of the same data type as was declared in the Return Data Type Statement
at the start of the function declaration. The return data type of a function can be only one of four
possible data types: INT (32 bits), REAL (32 bits), STRING (255 bytes), or OBJECT (32 bits). If no
Return Data Type Statement is declared, the function will not be able to return any type of data.
If the RETURN Statement within the function encounters a different data type to that declared in the
Return Data Type Statement, the value is converted to the declared return data type. For information
about the Return Data Type Statement, see the section titled 'Declaring the Return Data Type'.
FUNCTION, INT, REAL, STRING, and OBJECT are Cicode keywords and as such, are reserved.

NOTE: In the following function syntax example, every placeholder shown inside arrow brackets (
<placeholder> ) should be replaced in any actual code with the value of the item that it
describes. The arrow brackets and the word they contain should not be included in the
statement, and are shown here only for your information.

To declare the value that will be returned to the calling code, you must replace the <ReturnValue>
placeholder in the following example with an appropriate data value to match the Return Data Type as
declared in the function.
38 Cicode Function Syntax

<ReturnDataType>
FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
<Statement> ;
RETURN <ReturnValue> ;
END
The following example returns an integer of value 5:

INT
FUNCTION
FunctionName ( <Arguments> )
<Statement> ;
INT Status = 5;
<Statement> ;
RETURN Status;
END

The RETURN statement passes a value back to the calling procedure (either another function,
command or expression). Outside of the function, the return value can be read by the calling
statement. For example, it can be used by the caller as a variable (in a command), or animated (in an
expression).
 Chapter 3 - Variables

A variable is a named location in the computer’s memory where data can be stored. Variables can
store the basic data types - strings, integers, and real numbers - but each variable is specific for its data
type. For example, if you set up a variable to store an integer value, you cannot use it for real numbers
or strings.

NOTE: Each data type uses a fixed amount of memory - integers use 4 bytes of memory, real
numbers use 4 bytes, and strings use 1 byte per character. PLC INT types use only 2 bytes.

The computer allocates memory to variables according to the data type and the length of time you need
the variable to be stored.
Real-time variables (such as PLC variables) are already permanently stored in database files on your
hard disk. Any variable you use in a database field command or expression must be defined as a
variable tag, or the compiler will report an error when the system is compiled.

Declaring Variable Properties

You must declare each variable used in your functions (except for variables that are configured as
variable tags). In the declaration statement, you specify the name and data type of the variable. You
can also set a default value for the variable.

Declaring the Data Type

You can use variables of the following data types:

INT Integer (32 bits) -2,147,483,648 to 2,147,483,647

REAL Floating point (32 bits) -3.4E38 to 3.4E38

STRING Text string (256 bytes - Null terminated) ASCII (null terminated)

OBJECT ActiveX control

NOTE: 1) If you want to specify a Digital data type, use the Integer type. Digital types can either
be TRUE(1) or FALSE(0), as can Integer types.
2) Cicode INT types are 32 bit, whereas PLC INT types are only 16 bit.
3) Global Cicode STRING types are only 128 bytes.
40 Chapter 3 - Variables

Naming Variables

Throughout the body of the function, the variable is referred to by its name. You can name a variable
any valid name except for a reserved word, for example:

STRING sStr;
REAL Result;
INT x, y;
OBJECT hObject;

The first 32 characters of a variable name must be unique.

Setting Default Variable Values

When you declare variables, you can set them to an initial (or startup) value, for example:

STRING Str = "Test";

REAL Result = ;
INT x = 20, y = 50;

Using Variable Scope

Scope refers to the accessibility of a function and it's values. A Cicode variable can be defined as any
one of three types of scope - Global, Module, and Local. By default, Cicode variables are Module
scope, unless they are declared within a function.
All variables have the following format:

DataType Name [=Value];

Global Cicode Variables

A Global Cicode variable can be shared across all Cicode files in the system (as well as across
include projects). They cannot be accessed on pages or databases (e.g. Alarm.dbf).
Global Cicode variables are prefixed with the keyword GLOBAL, and must be declared at the
start of the Cicode file. For example:

GLOBAL STRING sDefaultPage = "Mimic";

INT
FUNCTION
MyPageDisplay(STRING sPage)
INT iStatus;
 Chapter 3 - Variables 41

iStatus = PageDisplay(sPage);
IF iStatus <> 0 THEN
PageDisplay(sDefaultPage);
END

RETURN iStatus;

END
The variable sDefaultPage could then be used in any function of any Cicode file in the system.

NOTE: 1) You should use Global variables with caution - if you have many such variables being
used by many functions, finding bugs in your program can become very time consuming.
Use Local variables wherever possible.
2) Global Cicode STRING types are only 128 bytes, instead of 256 bytes.

Module Cicode Variables

A Module Cicode variable is specific to the file in which it 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. For example:

STRING sDefaultPage = "Mimic";

INT
FUNCTION
MyPageDisplay(STRING sPage)
INT Status;

Status = PageDisplay(sPage);
IF Status <> 0 THEN
PageDisplay(sDefaultPage);
END

RETURN Status;

END

INT
FUNCTION
DefaultPageDisplay()

PageDisplay(sDefaultPage);

END
42 Chapter 3 - Variables

NOTE: You should use Module variables with caution - if you have many such
variables being used by many functions, finding bugs in your program can become very
time consuming. Use Local variables wherever possible.

Local Cicode Variables

A Local Cicode variable is only recognised by the function within which it is declared, and can
only be used by that function. You must declare Local variables before you can use them.
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.
Local variables always take precedence over Global and Module variables. If you define a Local
variable in a function with the same name as a Global or Module variable, the Local variable is
used; the Global/Module variable is unaffected by the function. This situation should be avoided,
however, as it is likely to cause confusion.

Using Database Variables

You can use any variable that you have defined in the database (with the Variable Tags form) in your
functions. To use a database variable, specify the tag name:

<Tag>
Where Tag is the name of the database variable. For example, to change the value of the database
variable "LT131" at run time, you would use the following statement in your function:

LT131=1200; !Changes the value of LT131 to 1200

Using Arrays

An array is a collection of variables of the same data type, in the form of a list or table. You name and
declare an array in the same way as any other variable. You can then refer to each element in the array
by the same variable name, with a number (index) to indicate its position in the array.
 Chapter 3 - Variables 43

Declaring Array Properties

Arrays have several properties that you must declare to the compiler along with the array name: its
data type, size and dimension. You can also set default values for individual elements of the array. An
Array declaration has the following syntax:

DataType Name[Dim1Size,{Dim2Size},{Dim3Size}]{=Values};

Declaring the Array Data Type

As with any other Cicode variable, arrays can have four data types:
INT Integer (32 bits)

REAL Floating point (32 bits)

STRING Text string (255 bytes)

OBJECT ActiveX object (32 bits)

Naming Arrays

Throughout the body of the function, the array is referred to by its name, and individual elements of an
array are referred to by their index. The index of the first element of an array is 0 (i.e. a four element
array has the indices 0,1,2, and 3). You can name a variable any valid name except for a reserved
word, for example:

STRING StrArray[5]; ! list

REAL Result[5][2]; ! 2-D table
INT IntArray[4][3][2]; ! 3-D table

Declaring the Array Size

You must declare the size of the array (the number of elements the array contains), for example:

STRING StrArray[5];
This single dimension array contains 5 elements. The compiler multiplies the number of elements in
the array by the size of each element (dependent upon the data type), and allocates storage for the
array in consecutive memory locations.
44 Using Arrays

NOTE: 1. You cannot declare arrays Local to a function. However, they can be declared as
Module (i.e. at the beginning of the Cicode file), or Global.
2. When referring to the array within your function, you must not exceed the size you set
when you declared the array. The example below would cause an error:
STRING StrArray[5];
:
StrArray[10] = 100;
:
The compiler allows storage for 5 strings. By assigning a value to a 10th element, you cause
a value to be stored outside the limits of the array, and you could overwrite another value
stored in memory.

Setting default (initial) Array values

When you declare an array, you can (optionally) set the individual elements to an initial (or start-up)
value within the original declaration statement. For instance, naming a string array "ArrayA", sizing it
to hold 5 elements, and initialising the array with string values, would look like the following example:

STRING ArrayA[5]="This","is","a","String","Array";
This array structure would contain the following values:

ArrayA[0]="This"
ArrayA[1]="is"
ArrayA[2]="a"
ArrayA[3]="String"
ArrayA[4]="Array"

Passing Array Elements as Function Arguments

To pass an array element to a Cicode function, you must provide the element's address - for example:

/* Pass the first element of ArrayA. */

MyFunction (ArrayA[0])
/* Pass the second element of ArrayA. */
MyFunction (ArrayA[1])
/* Pass the fifth element of ArrayA. */
MyFunction (ArrayA[4])
 Chapter 3 - Variables 45

Using One-Dimensional Arrays

STRING ArrayA[5]="This","is","a","String","Array";
This array sets the following values:

ArrayA[0]="This"
ArrayA[1]="is"
ArrayA[2]="a"
ArrayA[3]="String"
ArrayA[4]="Array"

Using Two-Dimensional Arrays

REAL ArrayA[5][2]=1,2,3,4,5,6,7,8.3,9.04,10.178;
This array sets the following values:

ArrayA[0][0]=1 ArrayA[0][1]=2
ArrayA[1][0]=3 ArrayA[1][1]=4
ArrayA[2][0]=5 ArrayA[2][1]=6
ArrayA[3][0]=7 ArrayA[3][1]=8.3
ArrayA[4][0]=9.04 ArrayA[4][1]=10.178

Using Three-Dimensional Arrays

INT ArrayA[4][3][2]=1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,
16,17,18,19,20,21,22,23,24;
This array sets the following values:

ArrayA[0][0][0]=1 ArrayA[0][0][1]=2 ArrayA[0][1][0]=3

ArrayA[0][1][1]=4 ArrayA[0][2][0]=5 ArrayA[0][2][1]=6
ArrayA[1][0][0]=7 ArrayA[1][0][1]=8 ArrayA[1][1][0]=9
ArrayA[1][1][1]=10 ArrayA[1][2][0]=11 ArrayA[1][2][1]=12
ArrayA[2][0][0]=13 ArrayA[2][0][1]=14 ArrayA[2][1][0]=15
46 Using Arrays

ArrayA[2][1][1]=16 ArrayA[2][2][0]=17 ArrayA[2][2][1]=18

ArrayA[3][0][0]=19 ArrayA[3][0][1]=20 ArrayA[3][1][0]=21
ArrayA[3][1][1]=22 ArrayA[3][2][0]=23 ArrayA[3][2][1]=24

Using Arrays in Functions

You use arrays in your functions in the same way as other variables, but arrays have special properties
that, in many situations, reduce the amount of code you must write.

Using Array elements in Loops

You can set up loops that deal efficiently with arrays by incrementing the index number. The
following example shows a method of initialising an array:

REAL Array[10]
:
FOR Counter = 0 TO 9 DO
Array[Counter] = 0
END
RETURN Total
:

Using the Table (Array) Functions

Cicode has in-built functions for processing arrays:

To perform calculations (max, min, total, etc.) on array elements

To look up the index number of an array element

To shift the elements of an array left or right

Converting and Formatting Variables

Citect provides four functions for converting integers and real numbers into strings, and vice versa.
IntToStr() converts an integer variable into a string

RealToStr() converts a floating-point variable into a string

StrToInt() converts a string into an integer variable

 Chapter 3 - Variables 47

StrToReal() converts a string into a floating-point variable

You can convert data types without using these Cicode functions, but the result of the format
conversion might not be what you expect. If you want total control over the conversion process, use
the appropriate Cicode functions.

NOTE: Variables of type OBJECT cannot be converted to any other type.

When variables are automatically converted, or when the return value from a function call is
converted, specific rules apply.

Converting Integers to Strings

IntVar=5;
StringVar=IntVar;

The value of StringVar is set to "5".

The format of the string is specified when the variable is defined in the database. However you can
override this default format with the string format (:) operator, and use the # format specifier to set a
new format. For example:

IntVar=5;
StringVar=IntVar:####

The value of StringVar = " 5". (The '#' formatting characters determine the size and number of
decimal places contained in the string, i.e a length of 4 with no decimal places.)

Converting Real Numbers to Strings

RealVar=5.2;
StringVar=RealVar;
The value of StringVar is set to "5.2".

NOTE: Unpredictable results may occur if you use large numbers with a large number of decimal
places.

The format of the string is specified when the variable is defined in the database. However you can
override this default format with the string format (:) operator, and use the # format specifier to set a
new format. For example:

StrTag1=RealTag1:######.###
48 Converting and Formatting Variables

The value of StringVar = " 5.200". (The '#' formatting characters determine the size and number of
decimal places contained in the string, i.e. a length of 10 including a decimal point and three decimal
places.)

Converting Strings to Integers

StringVar="50.25";
IntVar=StringVar;

The value of IntVar is set to 50. If StringVar contains any characters other than numeric characters,
IntVar is set to 0.

Converting Strings to Real Numbers

StringVar="50.25";
RealVar=StringVar;

The value of RealVar is set to 50.25. If StringVar contains any characters other than numeric
characters, RealVar is set to 0.

Formatting Text Strings in Cicode

A string in Cicode is always represented as text positioned between double quote ( " ) delimiters. For
example:

"This is my text string."

A string value can be assigned to a string variable. For example:

STRING sMyStringVariable;
sMyStringVariable = "This is my text string.";
More than one string can be joined together (concatenated) using the Cicode 'plus' mathematical
operator ( + ). For example:

STRING sMyStringVariable;
sMyStringVariable = "This is my text string." + "This is my second
text string.";
The two strings would be joined together and assigned to the string variable 'sMyStringVariable'.
However, if subsequently displayed somehow, like in the following MESSAGE example, the
 Chapter 3 - Variables 49

concatenated string would look wrong because there is no space character positioned between the
string sentences.

STRING sMyStringVariable;
sMyStringVariable = "This is my text string." + "This is my second
text string.";
MESSAGE("String Concatenation Example",sMyStringVariable,32);

To overcome this potential formatting problem, you could make sure an extra space was included as
the last character in the strings, or you could include the space as a third string in the concatenation.
For example:

sMyStringVariable = "This is my text string. " + "This is my

second text string. ";
or
sMyStringVariable = "This is my text string." + " " + "This is my
second text string. ";
However, these are considered poor programming practices, and are not recommended.
A better option, is to make use of special string formatting commands, known as 'escape sequences'.
If the two strings (as used in the previous example), were formatted using appropriate escape
sequences positioned within the strings, and subsequently displayed somehow, like in the following
MESSAGE example, the concatenated string would look very different, For example:

STRING sMyStringVariable;
STRING sNewLine = "^n";
sMyStringVariable = "This is my text string." + sNewLine + "This
is my second text string.";
MESSAGE("String Concatenation Example",sMyStringVariable,32);
50 Converting and Formatting Variables

Strings and string variables can also be concatenated as in the previous example. Notice how the
newline escape sequence ( ^n ) was assigned to the string variable 'sNewLine', and how this value was
concatenated between the other strings and assigned to the string variable 'sMyStringVariable' for
display in the MESSAGE function.

Escape Sequences (string formatting commands)

Cicode supports several escape sequences that you can use in text strings, for custom formatting of the
string. Using appropriate escape sequences, as listed below, you can format the string display to do
such things as break into separate lines at specific positions, insert tab spaces, insert quotes, or to
display Hexadecimal numbers.
All escape sequences are preceded by a caret ( ^ ) character. The caret character is interpreted as a
special instruction, and together with the characters immediately following it, are treated as an escape
sequence formatting command. The escape sequences used in Cicode are:
^b backspace
^f form feed
^n new line
^t horizontal tab
^v vertical tab
^' single quote
^" double quote
^^ caret
^r carriage return
^0xhh where hh is a hexadecimal number (for example, ^0x1A)
 Chapter 4 - Operators

Using Data Operators

With Cicode, you can use the data operators that are standard in most programming languages:
mathematical, bit, relational, and logical operators.

Using Mathematical Operators

Standard mathematical operators allow you to perform arithmetic calculations on numeric variables -
integers and floating point numbers.

Operator Description
+ Addition

- Subtraction

* Multiplication

/ Division

MOD Modulus (Remainder)

Examples:

Command PV12 = PV10 + PV11;

Comment PV12 is the sum of PV10 and PV11

Command Counter = Counter - 1;

Comment The value of Counter is decreased by 1

52 Using Data Operators

Command PV12 = Speed * Counter;

Comment PV12 is the product of Speed and Counter

Command Average = Total / ShiftHrs;

Comment Average is Total divided by ShiftHrs

Command Hold = PV12 MOD PV13;

Comment If PV12 = 10 and PV13 = 8, Hold equals 2

(the remainder when PV12 is divided by
PV13)

NOTE: Cicode uses the standard order of precedence, i.e. multiplication and division are calculated
before addition and subtraction. In the statement A=1+4/2, 4 is divided by 2 before it is
added to 1, and the result is 3. In the statement A=(1+4)/2 , 1 is first added to 4 before the
division, and the result is 2.5.

You can also use the addition operator (+) to concatenate (join) two strings.

Operator Description
+ Concatenate
Example:

Command Message = "For info see " +

"Supervisor";

Comment Message now equals "For info see

Supervisor"

Using Bit Operators

With a bit operator, you can compare the corresponding bits in two numeric expressions. (A bit is the
smallest unit of data a computer can store.)
 Chapter 4 - Operators 53

Operator Description
BITAND AND

BITOR OR

BITXOR Exclusive OR
Examples:

Command Tag3 = Tag1 BITAND Tag2;

Command Tag3 = Tag1 BITAND 0xFF;

Command Tag3 = Tag1 BITOR Tag2;

Command Tag3 = Tag1 BITXOR Tag2;

Using Relational Operators

Relational operators describe the relationship between two values. The relationship is expressed as
one value being larger than, the same as, or smaller than another. You can use relational operators for
both numeric and string variables, however you can only test variables of the same type. A numeric
variable cannot be compared with a string variable.

Operator Description
= Is equal to

<> Is not equal to

< Is less than

> Is greater than

<= Is less than or equal to

>= Is greater than or equal to

54 Using Data Operators

Examples:

Command IF Message = "Alarm Active" THEN ...

Expression PV12 <> PV10;

Command IF (Total + Count) / Avg < 10 THEN ...

Expression Counter > 1;

Command IF PV12 <= PV10 THEN ...

Expression Total >= Shift * Hours;

Using Logical Operators

With logical operators, you can test several conditions as either TRUE or FALSE.

Operator Description
AND Logical AND

OR Logical OR

NOT Logical NOT

Examples:

Command Result = (PV12 = 10 AND PV13 = 2);

Comment If PV12 equals 10 and PV13 equals 2 then

Result is TRUE(1)

Expression Motor_1 AND Motor_2;

Comment If both Motor_1 and Motor_2 are TRUE, i.e.

Digital bits are 1 or ON, then the expression
is TRUE
 Chapter 4 - Operators 55

Expression PV12 = 1 OR PV13 > 2 OR Counter <>

0;

Comment If either PV12 equals 1 or PV13 is greater

than 2 or Counter is not equal to 0, then the
expression is TRUE

Command Result = (Motor1_Ol OR Motor2_Ol);

Comment If either Motor1_Ol or Motor2_Ol is TRUE,

i.e. Digital bit is 1 or ON, then Result is
TRUE (1)

Command IF NOT PV12 = 10 THEN ...

Comment If PV12 does not equal 10 then the result is

TRUE. This is functionally identical to IF
PV12 <> 10 THEN . . .

Expression NOT Tag_1;

Comment This expression is TRUE if Tag_1 = 0. This

is most commonly used for testing digital
variables
56 Using Data Operators

Order of Precedence of Operators

All operators have a set of rules that govern the

order in which operations are performed. These
rules are called the order of precedence. The
precedence of Cicode operators from highest to
lowest is:
1. ()

2. NOT

3. *, /, MOD

4. :

5. +, -

6. >, <, <=, >=

7. =, <>

8. AND

9. OR

10. BITAND, BITOR, BITXOR

 Chapter 5 - Conditional Executors

Using Conditional Executors

The statements that control decisions and loops in your functions are called conditional executors.
Cicode uses four conditional executors: IF, FOR, WHILE, and SELECT CASE.

Setting IF ... THEN Conditions

The IF statement executes one or more statements based on the result of an expression. You can use
IF in one of two formats: IF THEN and IF THEN ELSE.
IF Expression THEN
Statement(s);
END
-or-
IF Expression THEN
Statement(s);
ELSE
Statement(s);
END
When you use the IF THEN format, the statement(s) following are executed only if the expression is
TRUE, for example:

INT Counter;

IF PV12 = 10 THEN
Counter = Counter + 1;
END
58 Using Conditional Executors

In this example, the Counter increments only if the tag PV12 is equal to 10, otherwise the value of
Counter remains unchanged. You can include several statements (including other IF statements),
within an IF statement, for example:

INT Counter;

IF PV12 = 10 THEN
Counter = Counter + 1;
IF Counter > 100 THEN
Report("Shift");
END
END

In this example, the report runs when the Counter increments, i.e. when PV12 = 10, and the value of
the counter exceeds 100.
You can use the IF THEN ELSE format for branching. Depending on the outcome of the expression,
one of two actions are performed, for example:

INT Counter;

IF PV12 = 10 THEN
Report("Shift");
ELSE
Counter = Counter + 1;
END

In this example, the report runs if PV12 is equal to 10 (TRUE), or the counter increments if PV12 is
anything but 10 (FALSE).

Using FOR ... DO Loops

A FOR loop executes a statement or statements a specified number of times.

FOR Variable=Expression To Expression DO
Statement(s);
END

The following function uses a FOR loop:

STRING ArrayA[5]="This","is","a","String","Array";
INT
FUNCTION
 Chapter 5 - Conditional Executors 59

DisplayArray()
INT Counter;

FOR Counter = 0 TO 4 DO
Prompt(ArrayA[Counter]);
Sleep(15);
END
END

This function displays the single message "This is a String Array" on the screen one word at a time
pausing for 15 seconds between each word.

Using WHILE ... DO Conditional Loops

A WHILE loop executes a statement or statements in a loop as long as a given condition is true.
WHILE Expression DO
Statement(s);
END
The following code fragment uses a WHILE loop:

INT Counter;

WHILE DevNext(hDev) DO
Counter = Counter + 1;
END

/* Count the number of records in the device (hDev)*/

NOTE: Be careful when you use WHILE loops in your Cicode functions - WHILE loops can cause
excessive loading of the CPU, and therefore reduce system performance. If you use a
WHILE loop to loop forever, you should call the Cicode function Sleep()so that Citect can
schedule other tasks. The Sleep() function increases the performance of your Citect system
if you use many WHILE loops.

Nested Loops

You can "nest" one loop inside the other. That is, a conditional statement can be placed completely
within (nested inside) a condition of another statement.
60 Using Conditional Executors

Using the SELECT CASE statement

The SELECT CASE statement executes on several groups of statements, depending on the result of an
expression. SELECT CASE statements are a more efficient way of writing code that would otherwise
have to be done with nested IF THEN statements.
SELECT CASE Expression
CASE CaseExpression1,CaseExpression2
Statement(s);
CASE CaseExpression3 TO CaseExpression4
Statement(s);
CASE IS >CaseExpression5,IS<CaseExpression6
Statement(s);
CASE ELSE
Statement(s);
END SELECT
Where CaseExpressionn is any one of the following forms:
- expression
- expression TO expression
Where the TO keyword specifies an inclusive range of values. The smaller value must be
placed before TO.
- IS <relop> expression.
Use the IS keyword with relational operators (<relop>). Relational operators that may be used
are <, <=, =, <>, >, >= .

If the Expression matches any CaseExpression, the statements following that CASE clause are
executed up to the next CASE clause, or (for the last clause) up to the END SELECT. If the
Expression matches a CaseExpression in more than one CASE clause, only the statements following
the first match are executed.
The CASE ELSE clause is used to indicate the statements to be executed if no match is found between
the Expression and any of the CaseExpressions. When there is no CASE ELSE statement and no
CaseExpressions match the Expression, execution continues at the next Cicode statement following
END SELECT.
You can use multiple expressions or ranges in each CASE clause. For example, the following line is
valid:
 Chapter 5 - Conditional Executors 61

CASE 1 To 4, 7 To 9, 11, 13, Is > MaxNumber

You can also specify ranges and multiple expressions. In the following example, CASE matches
strings that are exactly equal to "everything", strings that fall between "nuts" and "soup" in
alphabetical order, and the current value of "TestItem":
CASE "everything","nuts" To "soup",TestItem
SELECT CASE statements can be nested. Each SELECT CASE statement must have a matching END
SELECT statement.
For example, if the four possible states of a ship are Waiting, Berthed, Loading, and Loaded, the
Select Case statement could be run from a button to display a prompt detailing the ship’s current state.

SELECT CASE iStatus

CASE 1
Prompt("Waiting");
CASE 2
Prompt("Berthed");
CASE 3
Prompt("Loading");
CASE 4
Prompt("Loaded");
CASE Else
Prompt("No Status");
END SELECT
 Chapter 6 - Advanced Cicode Tasks

This section introduces and explains event handling, Citect tasks, Citect threads, how Citect executes,
and multitasking - including foreground and background tasks, controlling tasks, and pre-emptive
multitasking.

Handling Events
Cicode supports event handling. You can define a function that is called only when a particular event
occurs. Event handling reduces the overhead that is required when event trapping is executed by using
a loop. The following example illustrates the use of the OnEvent()function:

INT
FUNCTION MouseCallback()

INT x, y;

DspGetMouse(x,y);
Prompt("Mouse at "+x:####+","+y:####);

RETURN 0;

END

OnEvent(0,MouseCallback);
The function "MouseCallBack" is called when the mouse is moved - you do not need to poll the mouse
to check if it has moved. Citect watches for an event with the OnEvent() function.
Because these functions are called each time the event occurs, you should avoid complex or time
consuming statements within the function. If the function is executing when another call is made, the
function can be blocked, and some valuable information may be lost. If you do wish to write complex
event handling functions, you should use the queue handling functions provided with Cicode.

How Citect Executes

Your multi-tasking operating system gives Citect access to the CPU through threads. However, this
access time is not continuous, as Citect must share the CPU with other applications and services.

NOTE: Be careful when running other applications at the same time as Citect. Some applications
are very demanding on the CPU and degrade the performance of Citect.
64 Chapter 6 - Advanced Cicode Tasks

The Citect process has many operations to perform, including I/O processing, alarm processing,
display management, and Cicode execution - operations that must be performed continuously. And,
because Citect is a real-time system, it absolutely must perform the critical tasks within a minimum
time - at the expense of others. For this reason, Citect is designed to be multitasking, so it can
efficiently manage it's own tasks.
Citect performs all of its tasks in a specific order in a continuous loop (cycle). Citect's internal tasks
are scheduled at a higher priority than that of Cicode and have access to the CPU before the Cicode.
For example, the Alarms, Trends, and I/O Server tasks all get the CPU before any of your Cicode
tasks. The reports are scheduled at the same priority as your Cicode. Citect background spoolers and
other idle tasks are lower priority than your Cicode.
For Cicode, which consists of many tasks, Citect uses round-robin single priority scheduling. With
this type of scheduling each task has the same priority. When two or more Cicode tasks exist, they
each get a CPU turn in sequence. This is a simple and reliable method of CPU scheduling.

NOTE: If a Cicode task takes longer than its designated CPU time to execute, it is preempted until
the next cycle - continuing from where it left off. This ensures that all Cicode gets a chance
to execute.

Multitasking

Multitasking is when you can run more than one task at the same time. Windows supports this feature
at the application level. For example you can run MS-Word and MS-Excel at the same time.
Citect also supports multitasking internally; that is you can tell Citect to do something, and before
Citect has completed that task you can tell Citect to start some other task. Citect will perform both
tasks at the same time. Citect automatically creates the tasks, all you have to do is call the functions.
Multitasking is a feature of Citect not the operating system. Most applications cannot do this, for
example if you start a macro in Excel, while that macro is running you cannot do any other operation
in Excel until that macro completes.
A multitasking environment is useful when designing your Cicode. It allows you to be very flexible,
allowing the operator to perform one action, while another is already taking place. For example, you
can use Cicode to display two different input forms at the same time, while allowing the operator to
continue using the screen in the background.

NOTE: It is important that your Cicode is tidy and efficient. Please refer to the Defensive
Programming topic of the Cicode Programming Standard.

Foreground and Background Tasks

Cicode tasks (or threads) can be executing in either foreground or background mode. A foreground
task is one that displays and controls animations on your graphics pages. Any expression (not a
 Chapter 6 - Advanced Cicode Tasks 65

command) entered in a property field (i.e. Text, Rectangle, Button, etc.) is executed as a foreground
task. All other commands and expressions are executed in background mode.
The difference between a background and foreground task is that a background task can be pre-
empted. i.e. If system resources are limited, the task (e.g. the printing of a report) can pause to allow a
more critical task to be executed. When the critical task is completed (or when system resources
become available) the original task resumes. Foreground tasks are considered critical and can never
be pre-empted.

Controlling Tasks

You can use the Task functions to control the execution of Cicode tasks, and use the Citect Kernel at
runtime to monitor the tasks that are executing. Since Citect automatically creates new tasks
(whenever you call a keyboard command, etc.), schedules them, and destroys then when they are
finished, most users will not need to be concerned with them.
Sometimes it is desirable to manually 'spawn' a new task. For example, suppose your Cicode is polling
an I/O Device (an operation which must be continuous), but a situation arises that require operator
input. To display a form would temporarily halt the polling. Instead you can spawn a new task to get
the operator input, while the original task continues polling the device.

NOTE: The TaskNew Cicode function is used to spawn new tasks.

Pre-emptive Multitasking

Cicode supports pre-empted multitasking. If a Cicode task is running, and a more important task is
scheduled, Citect will suspend the original task, complete the more important task and return to the
original task.
Preemption is supported between Cicode threads and other internal process performed by Citect. You
can, therefore, write Cicode that runs forever (e.g. a continuous while loop) without halting other
Cicode threads or Citect itself. For example:

INT FUNCTION MyLoopFunction()

WHILE TRUE DO

// Whatever is required in the continuous loop

Sleep(1); // Optional
END
END
In the above example, the function Sleep()is used to force preemption. The Sleep() function is
optional, however it will reduce the load on the CPU, because the loop is suspended each second (it
will not repeat at a high rate).
 Chapter 7 - Editing and Debugging Cicode

The Cicode Editor

The Cicode Editor is the code editing tool provided with Citect for the writing, editing, and debugging
of your Cicode code. The Cicode Editor is simple to use, behaves similarly to other code editing tools
like Microsoft Dev Studio, and contains many advanced editing features such as:

Dockable Windows and Toolbars

Syntax highlighting - colour highlighting of syntax functions

IntelliSense AutoPrompt - function definition tooltips

IntelliSense AutoComplete - automatic inline prompting and completion of functions complete
with all parameters

AutoCaseCorrect - automatic case correction of function keywords

AutoIndent - automatic indent alignment of code

AutoScroll - automatic mouse middle button support

Drag and drop - copy or move of selected text

Bookmark and Breakpoint indicator bar - single click set and reset of bookmarks and breakpoints

Keyboard Shortcuts support - many new shortcuts available and linked to the other editor window
features, like Ctrl + F1 = tooltips, Ctrl + F2 = Bookmark navigation, F3 = find and replace repeat,
Ctrl + B = debug options, Esc = IntelliSense dismissal, etc.
The Cicode Editor has been integrated into the Citect Environment for easy access and quick starting.
It is automatically started any time you double click a Cicode file object in the Citect Explorer, or
when you click on the Cicode Editor button on the toolbar in Citect Explorer. See the section on 'How
to start the Cicode Editor'.
Cicode files are stored as text files, so they are easy to write and maintain. For more information on
Cicode files, see the section titled 'Using Cicode Files'. For an introduction to Cicode, see the section
on an 'Introduction to Cicode'.
You could use any text editor to view or edit the Cicode files, however, the Cicode Editor not only
provides the features listed above, but also provides integrated views specific to Cicode. This includes
such as the 'Breakpoint window', 'Output window', 'Global Variable window', 'Stack window', 'Thread
window', 'Compile Errors window', 'Watches window', and 'Files window'.
68 The Cicode Editor

To minimise potential future problems with maintaining your Cicode files, you should adopt a
programming standard as early as possible, as discussed in the section Cicode Programming Standard.
Be sure to maintain structured Cicode files, by logically grouping your Cicode functions within the
files, and by choosing helpful descriptive names. Modular programming methods are discussed in the
section titled 'Modular Programming'. Cicode functions are introduced in the section titled 'Cicode
Functions'. Debugging Cicode is discussed in the section titled 'Debugging Cicode'.

Starting the Cicode Editor

To start the Cicode Editor:

1. Select the Citect Explorer.

2. Open the Cicode Files folder in the project list area of your project.
3. Double click on any Cicode file (*.ci).
- or -
1. From the Tools menu, in any Citect application, select Cicode Editor.
- or -
1. Click on the Cicode Editor button.
 Chapter 7 - Editing and Debugging Cicode 69

Changing the default Cicode Editor

Some developers have a preference for more familiar editors. Citect allows you to use any text editor
supported by Windows (for example, ED for Windows, Windows Notepad, or Microsoft Word),
instead of the default Cicode Editor.

To change the default Cicode Editor:
1. Select the Project Editor.

2. From the Tools menu, select Options.

3. Enter the editor application file name in the Cicode Editor field.

NOTE: The application name of the default Cicode Editor is ctcicode.exe located in the Citect Bin
folder.
The application name for Notepad is notepad.exe, located in the Microsoft Windows
WINNT folder.
The relative path to the editor app must be included if the application is not stored in the
Citect Bin folder.

4. Click on the OK button to save the changes and close the form, or press Cancel to abort changes
without saving.
70 The Cicode Editor

Creating Cicode files

To create a new Cicode file:

1. Run the Cicode Editor.
2. From the File menu, select New.
or -
2. Click on the New button.

NOTE: Make sure you save the Cicode file soon after creating it. The file is only stored on disk
after you save it.

Creating Cicode functions

To create a new Cicode function:

1. Run the Cicode Editor.
2. From the File menu, select New.
3. Type in your new Cicode function in the blank space, or at the end of the file. You should format
the Cicode function correctly, following the documented syntax.
4. Save the Cicode file.
 Chapter 7 - Editing and Debugging Cicode 71

Saving Cicode files

To save a Cicode file:

1. From the File menu, select Save.
- or -
2. Click on the Save button.

3. If the file is new, you will be prompted by the Save as dialog. Citect will automatically suggest a
name.
4. Type in a new name in the File name field.
5. Click the Save button to save the file, or Cancel to abort the save.

TIP: If you want to save your Cicode file under a new name, select Save as instead of Save.
The original file will remain in your project under the original filename, until you delete it.
All source files in your project directory will be included when you compile your project.
72 The Cicode Editor

Opening existing Cicode files

To open a Cicode file:

1. Run the Cicode Editor.
2. From the File menu, select Open.
- or -
2. Click on the Open button.

3. Select a file from the list. You can use the dialog controls to open other projects and directories.
4. Click the Open button to open the file, or Cancel to abort.

TIP: Double clicking on any Cicode file (*.ci) in the Citect Explorer will launch the Cicode
Editor and open the Cicode file.
 Chapter 7 - Editing and Debugging Cicode 73

Deleting Cicode files

To delete a Cicode file:

1. Run the Cicode Editor.
2. From the File menu, select Open.
- or -
2. Click on the Open button.

3. Select the target file from the list. You can use the dialog controls to open other projects and
directories.
4. Press the Delete key.
5. Click the Yes button to confirm delete, or No to abort.
6. Click the Cancel button to close the Open form.

Finding text within Cicode files

To find text in a Cicode file:

1. From the Edit menu, select Find.
- or -
1. Click on the Find button.

2. Complete the Find dialog, filling in the Find what field.

3. Click the Find Next button to begin searching, or Cancel to abort. The search is performed down
the file from the cursor. Hits are highlighted.

Compiling Cicode files

To compile Cicode:
1. Run the Cicode Editor.
2. From the File menu, select Compile.
- or -
2. Click on the Compile button.

NOTE: You cannot compile Cicode functions individually. When you compile Citect, it
automatically compiles the entire contents of the project.
74 The Cicode Editor

Viewing Cicode compile errors

To view Cicode compile errors:

1. From the Compile Errors in the File menu of the Project Editor, click the Goto button. This
will automatically launch the Cicode Editor and open the appropriate file at the correct line.
- or -
1. Run the Cicode Editor.
2. From the View menu, select Compile Errors.
3. In the Compile Errors window, double click on the compile error you want to view.

Cicode Editor Options

Cicode error handling behaviour is controlled through the Cicode Editor Options Properties Dialog.
These allow you to set (and change) what should happen when errors occur in running Cicode, under
which circumstances the debugger should be started, and how the debugger behaves when in debug
mode.
There are three tabbed property pages of options within the Debugger Options Properties dialog:
1. View Windows and ToolBars tab
2. Options Properties tab
3. Language Formatter Properties tab

Docking Editor Windows and Toolbars

The view windows and toolbars of the Cicode Editor can be docked or free floating within the editing
and debugging environment.
Toolbars are docked by default within the toolbar area at the top of the Cicode Editor. Windows are
docked by default in the document display area at the lower portion of the Cicode Editor, beneath the
toolbar area.
Docked windows are those that resize themselves to fit totally within the Cicode Editor display area,
by docking (attaching) themselves to an internal edge of the display area. Docked windows cannot be
resized manually, and will share the display space with the Editor toolbars and other docked windows.
Docked windows and toolbars share the display space side-by-side, and do not obscure the view of
each other.
 Chapter 7 - Editing and Debugging Cicode 75

Free floating windows are those that are not docked to the editor, nor are necessarily constrained by
the editor boundaries. Free floating windows can be resized manually, and are subject to layering (Z-
order), in which they can be partly or wholly obscured by another window, and they could partly or
wholly obscure the view of another window themselves. The window or toolbar with the current
focus, is the one completely visible at the top of all other display window layers, partly or wholly
obscuring all those beneath it in the Z-order.
Windows and toolbars can be moved about in the Cicode Editor environment by clicking and dragging
the titlebar of a window, or non-button area of a button bar. Docking behaviour is by default, and can
be overridden by holding down the CTRL key during the drag-and-drop to force the window or bar to
be free floating.
The position of the mouse during the drop action determines which side the window or toolbar docks
to. Docking outlines of the window or toolbar are displayed with grey lines during the drag action to
indicate the potential docked position.

How to view/hide the Editor Options Properties Dialog

To view/hide the Editor Options Properties Dialog

1. Run the Cicode Editor.
2. From the Debug menu, select Options.
- or -
2. Press Ctrl + T, and select the appropriate Window from the dialog.
- or -
2. From the View menu, select Options, and select the appropriate Window from the dialog.
76 Cicode Editor Options

Cicode Editor Options – Windows and Bars tab

Cicode Editor Options – (View) Windows and Toolbars

The Windows and Bars tab displays the current display state of the listed Toolbars and Debug
Windows within the Cicode Editor. A tick mark in the checkbox next to the Window or Toolbar name
enables the display of that Window or Toolbar in the Citect Editor. A greyed-out checkbox indicates
that the window is disabled (presently unable to be displayed). For example: Many of the debug
windows which display the active state of project Cicode variables are disabled when a Cicode project
is not running, and therefore the Cicode Editor cannot be in debug mode).

TIP: Right-click anywhere in the toolbar area to view a drop-down menu list of available toolbars
and debug windows.
For a description of what each button does, see 'Using the Cicode Editor'.

Cicode Editor - Toolbar Options

File
Displays the File Toolbar

Edit
Displays the Edit Toolbar

Debug
Displays the DebugToolbar
 Chapter 7 - Editing and Debugging Cicode 77

Citect
Displays the CitectToolbar

Format
Displays the FormatToolbar

View
Displays the ViewToolbar

Bookmarks
Displays the BookmarksToolbar

TIP: For a description of what each button does, see 'Using the Cicode Editor'.

Cicode Editor - Window Options

The Cicode Editor has a number of editing and debug windows that you can use to display information
about running Cicode and CitectVBA. This information is particularly useful in gaining insight into
how your functions may be behaving.
The Cicode Editor windows available are:

Breakpoint window

Output window

Global Variable window

Stack window

Thread window

Compile Errors window

CitectVBA Watch window

Files window

To view/hide an Editor Window:

1. Run the Cicode Editor.
2. From the View menu, select the appropriate Window.
- or –
2. Click on the appropriate toggle
button in the View toolbar.
78 Cicode Editor Options

- or –
2. Right-click on an undocked part of the button bar, and select the appropriate Window from the
menu.
- or –
2. Press Ctrl + T, and select the appropriate Window from the dialog.
- or –
2. From the View menu, select Options, and select the appropriate Window from the dialog.

Breakpoint Window
Displays the Breakpoint Window, which is used to list all breakpoints that are currently set within
the project.
Double clicking on an item in the list will load the file into the editor and jump to the breakpoint
position.
Right-clicking on an item allows the enable/disable/removal of the list item.

The Breakpoint Window has the following fields:

File The full name and location of the code file in which the breakpoint exists.
Line The line number (in the code file) where the breakpoint is located.
Enabled Indicates if the breakpoint is enabled or not. A Yes indicates it is active, while a No
indicates it is not active.

Output Window
Displays the Output Window, which lists the output messages sent by Citect during debugging. It
states when threads start and terminate, and if a break occurs. This window will show messages
sent by the TraceMsg()function.
 Chapter 7 - Editing and Debugging Cicode 79

The Output window shows entries in the order that they occur:

NOTE: You must be in debug mode to view the messages.

Global Variable Window

Displays the Global Variables Window, which lists the names and values of all global variables
processed to date in the running project during debugging. A global variable is added to the list
when it is first assigned a value. Each time the Global variable is processed, its value will be
updated in the Global Variable Window.

NOTE: You must be in debug mode to view global variable values in this window.

Stack Window
Displays the Call Stack Window, which lists the stack values of the current thread. The stack
consists of the functions called (including the arguments), any variables used in the functions, and
80 Cicode Editor Options

return values. This is especially useful during debugging to trace the origin of the calling
procedures.

NOTE: A stack is a section of memory that is used to store temporary information. For
example, when you call a Cicode function, the variables used inside the function exist
only as long as the function runs.
To view the values of arguments and variables in a procedure, place a breakpoint within the
procedure under watch. When that breakpoint is reached, the Stack Window will display the
current call stack of the procedure containing the breakpoint. The values of the stack are updated
as the values change.

NOTE: You must be in debug mode to view this window.

Thread Window
Displays the Threads History Window.
 Chapter 7 - Editing and Debugging Cicode 81

The Thread Window has the following fields:

Name The name of the Cicode thread. This is the name of the function called to start the
thread (from the TaskNew()function for example).
If you click on the Name of the Cicode thread, you will make the selected thread the current focus of
the Debugger. The Debugger will change the display to show the source of the new thread.

NOTE: If the thread was not started from TaskNew(), the Name shown will be Command.

Hnd The Cicode thread handle.

CPU The amount of CPU the Cicode thread is currently using, as a percentage of the total
CPU usage. Cicode is very efficient and this value should be quite small (0-25%). If this value is
large it can indicate a problem with your Cicode. For example, values over 60% can indicate that
the thread is running in 'hard' loops, and needs a Sleep()function inserted.
State The state of the Cicode thread. The states are defined as follows:
Ready The Cicode is ready to be run.
Sleep Suspended using the Sleep()function.
Run The thread is running.
CPU_Time The total amount of CPU time that the Cicode thread has consumed. This tracks
how much CPU time the thread has used over its lifetime.

NOTE: You must be in debug mode to view this window.

Compile Errors Window

Displays the Compile Errors Window, which lists any code errors that have occurred during
compile. You can double-click on the file name in the list, to open that code file in the Cicode
Editor, and jump to the line of code that caused the compile error.
82 Cicode Editor Options

CitectVBA Watch Window

Displays the CitectVBA Watch Window. During debugging mode, you can use the CitectVBA
Watch window to watch the value of any CitectVBA variables in the current scope. Click in the
Variable column and type in the name of the variable under watch. As it comes into scope, its
value will be updated and displayed in the Value column.

NOTE: You must be in debug mode to view this window.

Files Window
Displays the Files Window containing three tabs.

The 'All Projects' tab displays a tree hierarchy view of all projects and their Cicode and CitectVBA
files available within Citect Explorer.

The 'Open Project' tab displays a tree hierarchy view of the currently selected project, and all
included projects. The currently selected project will always be the top entry.

The 'Open Files' tab lists the names of all files currently open for editing in the Cicode Editor.

NOTE: Clicking on any of the file names displayed in the tree will open that file in the editor
and give it the focus.
 Chapter 7 - Editing and Debugging Cicode 83

Cicode Editor Options – Option Properties tab

Cicode Editor Options – Option Properties

[Dynamic properties] Break on all hardware errors

Stops a Cicode thread if a hardware error occurs. A Cicode error will be generated and the thread
will terminate (without executing the rest of the function).

[Dynamic properties] Suspend all Cicode threads while stepping

All Cicode threads will be suspended while the debugger is stepping (or when the debugger reaches
a breakpoint, or the user performs a manual break). If you try to run any Cicode thread at such a
time (by pressing a button at runtime etc.), the Command paused while in debug mode message
will display in the runtime prompt line.
This option allows better isolation of faults, when your Cicode thread interacts with other threads.
Foreground Cicode cannot be suspended and will continue running when this option is set.

WARNING: This option will prevent all new Cicode threads from running (including
keyboard and touch commands), and should be used with caution on a running plant.

[Dynamic properties] Warning on break in foreground Cicode

If a break point is 'hit' in a foreground Cicode task, the Foreground Cicode cannot break (343)
error message is generated, and will be displayed on the Hardware Alarm page. Disable this option
to stop the alarm message from displaying.
84 Cicode Editor Options

[Citect startup options] Citect will start debugger on hardware errors

Citect will automatically start the debugger when a Cicode generated hardware error occurs. The
debugger will display the Cicode source file, and mark the location of the error.

WARNING: This option will interrupt normal runtime operation, and should only be used
during testing and commissioning of systems.

[Citect startup options] Notify debugger of errors in foreground Cicode

Citect will automatically start the debugger if an error occurs in a foreground task. The debugger
will display the Cicode source file, and mark the location of the error.
This option is overridden by the Citect will start debugger on hardware errors option. That is,
if the above option is disabled, then this option is disabled also.

NOTE: Foreground Cicode cannot be suspended. The break point will be marked, but you will
not be able to step through the function.

[Citect startup options] Allow remote debugging

Allows debugging of Cicode on this computer from a remote Citect computer.

[Citect startup options] Remote IP Address

The Windows Computer Name or TCP/IP address of the remote Citect computer.
The Windows Computer Name is the same as specified in the Identification tab, under the Network
section of the Windows Control Panel. You specify this name on the computer from which you are
debugging.
The TCP/IP address (e.g. 10.5.6.7 or plant.yourdomain.com) can be determined as follows:

For Windows NT4 or 2000, go to the Command Prompt, type IPCONFIG, and press the
[Enter] key.

For Windows 95 or 98, select Start | Run, type WINIPCFG, and press the [Enter] key.

[Debugger options] Save breakpoints between sessions

Save the location and states of breakpoints between running sessions of the Cicode Editor and
Debugger. This means breakpoints inserted using the Cicode Editor can later be recalled when an
error occurs - even though the file (and application) has been closed.

[Compile options] Incremental compile

Enables the incremental compilation of the project.
 Chapter 7 - Editing and Debugging Cicode 85

Cicode Editor Options – Language Formatter Properties tab

Cicode Editor Options – Language Formatter Properties tab

This dialog displays the currently selected programming language that the editor will use to format the
syntax of the file being edited in the code window. If you open a Cicode file (with a .Ci extension),
the current language formatter changes to Cicode. If you open a CitectVBA file (with a .bas
extension), the current language formatter changes to CitectVBA.
Similarly, if you open a file with neither a Cicode nor a CitectVBA extension, say a text file (with a
.txt extension), the editor will not know which language type you intend to use, and will not apply any
formatting to the file. You can use this dialog to select which programming language the file contains,
and it will format the file appropriately for display in the code window.

NOTE: The Cicode Editor can be used to edit any ASCII text based file, including Microsoft
JScript. The editor recognises JScript files (with a .jav extension) and will change the
current language formatter to JScript. Citect does not support JScript, and will not compile
it into your project. However, the editor can still be used separately to edit or create a
JScript file or any other ASCII text based file.

Current
Displays the currently selected programming language formatter for appropriate syntax colouring
of the file displayed in the code window.

Selection
Displays the range of possible programming languages that can be chosen as the current language
for formatting and display in the code window.
86 Debugging Cicode

Debugging Cicode
Some projects require the development of complex Cicode to implement advanced custom
functionality. One of the disadvantages of complex code is that if not constructed properly, it is prone
to errors. To help locate any errors, the Cicode Editor can switch into debug mode. You can then use
it to analyse running Cicode. You can turn debugging on and off as required, but Citect be running for
the debugger to work.

NOTE: The Cicode Editor cannot debug foreground Cicode. A break in a foreground Cicode will
result in the Foreground Cicode cannot break message.

How to switch to debug mode

To switch to debug mode:

1. Run the Cicode Editor.
2. From the Debug menu, select Start Debugging.
- or -
2. Click on the Toggle Debug button.

NOTE: If the current project is not running, Citect will compile and run it automatically. The bug
in the bottom right hand corner will be green when debugging.

How to debug a function

To debug a function:
1. Run the Cicode Editor.
2. Open the file containing the function you wish to debug.
3. Click on the Toggle Debug button to
start debugging.
- or -
3. From the Debug menu, select Start Debugging.

NOTE: If the current project is not running, Citect will compile and run it automatically. The bug
in the bottom right hand corner will be green when debugging.
 Chapter 7 - Editing and Debugging Cicode 87

4. Insert a breakpoint where you want to start debugging.

5. From the View menu, select any debug windows you want to use. If you are unsure, you can use
them all.
6. Initiate the thread by calling the function. You can do this directly from the Cicode window in
the Kernel, or by using a function, etc.
7. The function will break at the specified breakpoint. You can then use the step tools to step
through and trace your function.
8. Click on the Toggle Debug button to
stop debugging.
- or -
8. From the Debug menu, select Stop Debugging.

How to remotely debug a function

To remotely debug Cicode:

NOTE: To do this both computers must be running identical projects.

1. Click on the Cicode Editor button on

the computer that will be running Citect
(the remote).
2. From the Debug menu, select Options.
3. Check (tick) the Allow remote debugging option.
4. Click on the OK button to save the option.
5. Click on the Run button.
(you can close the Cicode Editor first)
- or -
5. From the File menu, select Run.
6. On the computer that will be debugging
Citect, click on the Cicode Editor
button.
7. From the Debug menu, select Options.
8. Enter the Windows Computer Name or TCP/IP address of the remote Citect computer.
88 Debugging Cicode

The Windows Computer Name is the same as specified in the Identification tab, under the
Network section of the Windows Control Panel. You specify this name on the computer from
which you are debugging.
The TCP/IP address (e.g. 10.5.6.7 or plant.yourdomain.com) can be determined as follows:

For Windows NT4 or 2000, go to the Command Prompt, type IPCONFIG, and press the
[Enter] key.

For Windows 95 or 98, select Start | Run, type WINIPCFG, and press the [Enter] key.
9. Click on the OK button to save the option.
10. Click on the debug button to start remote
debugging.

NOTE: Citect uses Named Pipes for remote debugging. To install the Named Pipe service on
Windows NT and 2000, you must enable the Server Network service in the Network section
of the Control Panel.

Debugging - Using Breakpoints

There are three ways for a processing thread to halt:

by manually inserting a breakpoint

by using the DebugBreak Cicode function

if a hardware error occurs
To debug a function, you must first be able to stop it at a particular point in the code. You can place a
breakpoint on any line in the source code functions. Breakpoints may be inserted or removed while
editing or debugging and do not need to be saved with the file.
For a hardware error to halt a function, you must have either the Break on all hardware errors or
Break on hardware errors in active thread option set (Debug menu - Options). When the break
occurs, the default Cicode Editor will be launched (if it is not open already), with the correct code file,
function, and break point line displayed. To launch the debugger in this case, you must have the
Citect will start debugger on hardware errors option set.
 Chapter 7 - Editing and Debugging Cicode 89

How to insert/remove a breakpoint

To insert/remove a breakpoint:
From within the 'Cicode Editing Window':
1. Position the cursor on the line where you want the breakpoint to be placed or removed.
2. Left click in the 'Debug Indicator Bar'.
- or -
2. Press F9.
- or -
2. From the Debug menu, select Insert/Remove Breakpoint.
- or -
2. Click on the Toggle Breakpoint button.

- or -
2. Right click, and select Insert/Remove Breakpoint from the popup menu.

NOTE: The breakpoint appears as a large red dot at the beginning of the line. (Symbolically similar
to a stop light.)

How to enable/disable a breakpoint

To enable/disable a breakpoint:
From within the 'Cicode Editing Window':
1. Position the cursor on the line where the breakpoint is located.
2. Press Ctrl + F9.
- or -
2. From the Debug menu, select Enable/Disable Breakpoint.
- or -
2. Right click, and select Enable/Disable Breakpoint from the popup menu.

NOTE: A disabled breakpoint appears as a large dark grey (disabled) dot at the beginning of the
line.
90 Debugging Cicode

Debugging - Stepping through the Code

Once you have halted a thread, the debugger will mark the position in the code with an arrow. Now
you can step through the function, line by line, and watch what happens in the debug window (see
below). The following tools are provided in the Cicode Editor, to control stepping through functions.
Step Into Advance the current Cicode thread by one statement. If the statement is a user
defined function, the debugger will step into it (the pointer will jump to the first line
of the source code).

Step Over Advance the current Cicode thread by one statement. If the statement is a user
defined function, the debugger will step over it (the function is not expanded).

Step Out Advance to the end of the current function and return. If there is no calling
function, the thread will terminate.

Continue Re-start normal execution of the current Cicode thread. If there are no further
breaks, the thread will terminate normally.
 Chapter 8 - Cicode Programming Standard

Cicode Programming Standard

The implementation of Standard Cicode practices means your Cicode will be more robust, more
predictable in its execution, and more maintainable and uniform in appearance - regardless of the
author(s). This will, at least, lend itself to a well engineered product produced by a team rather than a
group of individuals. This can be achieved by:

adopting modular programming techniques;

ensuring that programs are adequately described by suitable module headers; and

formatting code so that its readability is greatly improved.

Variable Declaration Standards

When declaring variables you should use consistent formatting. A variable declaration has up to five
parts. Each part is separated by at least one tab stop:

[<scope>] <type> <name> [=<initial value>] [<comment>]

The scope of the The Type of Variable names The initial value of An optional
variable (Local, variable - INT (32 should be as the variable (the comment which
Module, or Global). bits), REAL (32 descriptive as value it will gives a short
bits), STRING (255 possible to the real assume when it is description of the
bytes), or OBJECT purpose of the first used). variable.
(32 bits). variable.

KEY:
Parts contained within square brackets - [ ] - are optional. For example, you do not have
to specify the variable scope (it will default to Local if you do not).

Parts contained within greater than & less than signs - < > - should be replaced with the
relevant text/value. For example, you would replace <initial value> with an actual value.
(You would not bracket your value with greater than & less than signs.)

When declaring your variables, all parts of each should align vertically (the scope part of each should
be vertically aligned, the type part of each should be aligned, etc.). Each part of the declaration is
92 Variable Declaration Standards

allotted a set amount of space. If one part is missing, its space should be left blank. The missing part
should not affect the positioning of the next part:

Module int miRecipeMax =100 ;

int iRecipeMax ;
string sRecipeDefault="Tasty" ;

Variable Scope Standards

Local Variable Standards

Local Variables should be initialised, for example:
INT iFile = 0;
STRING sName = "";
INT bSuccess = FALSE;

Module Variable Standards

Module Variables should be initialised, for example:
MODULE INT mhForm = -1;
MODULE STRING msPageName = "Loop";

Global Variable Standards

Global Variables should be initialised, for example:
GLOBAL INT ghTask = -1;
GLOBAL STRING gsLastPage = "Menu";

Variable Naming Standards

The following naming conventions should be applied to variables:

Variable names should have a small case letter prefix as follows:

Type Prefix Used for

INT (32 bits) i index, loop counter

INT (32 bits) and OBJECT (32 bits) h handle

INT (32 bits) b boolean

(TRUE/FALSE)
 Chapter 8 - Cicode Programming Standard 93

REAL (32 bits) r real type variables

STRING (255 bytes) s string type variables

Variable names typically consist of up to 3 words. Each word in a variable name should start with
a capital letter, for example:
iTrendType, rPeriod, sFileName

Module variable names should be prefixed with an "m", for example:

miTrendType, mrPeriod, msFileName

Global variable names should be prefixed with a "g", for example:

giTrendType, grPeriod, gsFileName

Local variable names should not be prefixed (when you declare a variable without specifying the
scope, it is considered a Local variable by default):
iTrendType, rPeriod, sFileName

Standards for Constants, Variable Tags, and Labels

Constants
In Cicode there is no equivalent of #defines of C language, or a type that will force variables to be
constants (read-only variables). However, the variable naming convention makes constants easily
identifiable so developers will treat those variables as read-only variables.

Constants must have the prefix ‘c’

Constants must be declared and initialised at the beginning of the Cicode file and never
assigned a value again.

For example:
INT ciTrendTypePeriodic = 1;
INT ciTrendTypeEvent = 2;

STRING csPageName = "Mimic";

Variable Tags
Variable tags that have been defined in the database (with the Variable Tags form) can be used in
all functions in the Cicode files. Variable tags are identifiable because they will not have a prefix
(also, they are generally in upper case letters).
94 Standards for Constants, Variable Tags, and Labels

Labels
Labels, like Variable tags, can be used in all functions in the Cicode files. They can be either all
upper case letters or mixed case. In order to differentiate them from the Variable tags and other
Cicode variables they should have an ‘_’ (underscore) in front of them. For example:

_BILLING_EVENT, _UNIT_OFFLINE, _AfterHoursEvent

WARNING There are a few labels without an underscore defined in the Labels form in the
INCLUDE project. Although they do not follow the guidelines set in this document their
wide usage makes changing those labels very difficult.
These labels are: TRUE, FALSE, BAD_HANDLE, XFreak, XOutsideCL, XAboveUCL,
XBelowLCL, XOutsideWL, XUpTrend, XDownTrend, XGradualUp,
XGradualDown, XErratic, XStratification, XMixture, ROutsideCL,
RAboveUCL, RBelowLCL

Formatting Simple Declarations

The following conventions should be observed when formatting simple declarations:

Only one item should be declared per declaration; there should be no comma separated list of
variables; and

Tab stops should be used for declarations and indentation.

For example:
INT hFile,hForm; // WRONG

INT hFile; // RIGHT

INT hForm; // RIGHT
The reasons for this are:

All but the first identifier in the WRONG case are hidden and are often missed in a quick glance;

It is harder to add a comment or initialisation to an item in the WRONG case; and

All types, items, and initialisation within a group of declarations should be vertically aligned.

For example:
STRING sFileName = "temp.dat"; // WRONG
INT iOffset = -1; // WRONG
INT iState = 3; // WRONG

STRING sFileName = "temp.dat"; // RIGHT

INT iOffset = -1; // RIGHT
INT iState = 3; // RIGHT
 Chapter 8 - Cicode Programming Standard 95

Formatting Executable Statements

The following conventions should be observed when formatting executable statements:

Statements are placed on new lines, indented one tab stop from the level of their surrounding block.
DO NOT place more than one statement on a single line because all but the first will be
permanently lost. Although it may be argued that some statements are logically related, this is not
sufficient justification. If they are logically related, place the statements on consecutive lines and
separate the statements by a blank line before and after. For example:
hFile = -1; hForm = -1; // WRONG

hFile = -1; // RIGHT

hForm = -1; // RIGHT

IF statements can be used in one of the formats below. When indenting the IF statements, a tab
stop should be used. For example:

Simple IF block
IF <expression> THEN
.
.
END

IF-THEN-ELSE block
IF <expression> THEN
.
.
ELSE
.
.
END

Nesting statements should be used for ELSEIF blocks. For example:

Staggered
IF <expression> THEN
.
.
ELSE
IF <expression> THEN
.
.
ELSE
IF <expression> THEN
.
.
96 Formatting Executable Statements

ELSE
.
.
END
END
END

For WHILE and FOR statements refer to the on line help or Cicode Reference manual.

Formatting Expressions
The following conventions should be observed when formatting functions:

When an expression forms a complete statement, it should, like any other statement, occupy one or
more lines of its own and be indented to the current level. Operator should be surrounded by
spaces. For example:
i= i*10+c-'0'; // WRONG
i = i * 10 + c - '0'; // RIGHT

When a sub-expression is enclosed in brackets, the first symbol of the sub-expression should be
placed hard against the opening bracket. The closing bracket should be placed immediately after
the last character for the sub-expression. For example:
a = b * ( c - d ); // WRONG
a = b * (c - d); // RIGHT

The round brackets which surround the arguments of a function all attract no spaces, for example:
DisplayText( "hello" ); // WRONG
DisplayText("hello"); // RIGHT

Commas, whether used as operators or separators, would be placed hard against the previous
symbol and followed by a space. For example:
DevSeek(hDev ,Offset); // WRONG
DevSeek(hDev, Offset); // RIGHT

Comments
Much of this formatting section, has concerned itself with improving the readability of your code. The
assumption is that readable code is much easier to understand than unreadable code. Comments do not
improve readability but attempt directly to aid understanding and maintenance.
Comments embedded in code tend to create a dense mass of text and upset the flow of code.
Comments should all be placed in the notes of the function header so as not to clutter up the code.
Small one line comments are acceptable to explain some small part of the code which may become lost
in the normal header comment.
 Chapter 8 - Cicode Programming Standard 97

Formatting Functions
Cicode functions have up to seven parts: Scope, Type, Keyword, Name, Argument(s), Statement(s),
Keyword.

[Scope]

The scope of the function. If you do not specify a scope, the function will be Public by default. That
is, it will be available to all Cicode files, pages, and Citect databases (e.g. Alarm.dbf). To make a
function Private (i.e. only available within the file in which it is declared), you must prefix it with the
word PRIVATE.

[Type]

The return type of the function. This should be on a separate line.

Keyword

The keyword FUNCTION. This should be on a separate line.

Name

The function name. Function names should follow the Function Naming Standards. This should be on
a separate line.

Argument(s)

The argument list. The arguments are separated by commas and they can have default values. The
argument list is normally on the same line as the function name but multiple line argument list is also
acceptable if it improves readability.

Statement(s)

The statements. Each statement should be on a separate line.

Keyword

The keyword END which marks the end of the function. This should be on a separate line.
98 Formatting Functions

KEY:
Parts contained within square brackets - [ ] - are optional. For example, you do not have
to specify the function scope (it will default to Public if you do not).

Parts contained within greater than & less than signs - < > - should be replaced with the
relevant text/value. For example, you would replace <initial value> with an actual value.
You would not bracket your value with greater than & less than signs.

For example:

FUNCTION
PlotInit()
<statements>
END

INT
FUNCTION
PlotOpen(STRING sName, INT nMode)

INT hPlot = _BAD_HANDLE;

.
hPlot = …..;
.
RETURN hPlot;
END

PRIVATE
STRING
FUNCTION
WasteInfoName(INT nType, INT nMode)

STRING sName = "Sydney";

.
sName = …..;
.
RETURN sName;
END

Function Naming Standards

Function names should contain at least the following information:

A three to five letter description of the function type (Trend, Plot, Win);

A one or two word description of the data to be operated on (Info, ClientInfo, Mode);

A one word action to be taken (Get, Set, Init, Read); and
For example:
PlotInit();
 Chapter 8 - Cicode Programming Standard 99

TrendClientOpen();
TrendClientInfoRead();

Source File Headers

Source files (the files that contain your Cicode) should have a header to provide a basic overview of
the file. This header should be formatted as follows:
//** FILE: <name of file.CI>
//**
//** DESCRIPTION: <description of basically what is in the
file>
//**
//** FUNCTIONS: PUBLIC
//** <list of the PUBLIC functions contained
//** in this file>
//**
//** PRIVATE
//** <list of the PRIVATE functions contained
//** in this file>
//**
//*************** MODULE CONSTANTS***********************

<module constants> //<comments (optional)>

//**************** MODULE VARIABLES ***********************

<module variables> //<comments (optional)>

//*********************************************************

NOTES: 1) Declare all module variables at the MODULE VARIABLES section at the beginning of
the file; and
2) Initialise the module variables.

For example:
//** FILE: Recipe.CI
//**
//** DESCRIPTION: Contains all functions for gathering recipe
data.
//**
//** FUNCTIONS: PUBLIC
//** OpenRecipeDatabase
//** CloseRecipeDatabase
//** ReadRecipeData
//** WriteRecipeData
//** GatherRecipeData
100 Formatting Functions

//** RecipeForm
//** OpenRecipeDatabase
//**
//** PRIVATE
//** ButtonCallback
//**
//*************** MODULE CONSTANTS***********************

module int cmiRecipeMax =100; //Maximum number of recipes

//**************** MODULE VARIABLES ***********************

module int miRecipeNumber=0; //Minimum number of recipes

//*********************************************************

Function Headers

Functions should have a descriptive header, formatted as follows:

//** FUNCTION : <name of function>
//**
//** DESCRIPTION : <suggests the operation, application source
and
//** multi-tasking issues>
//** REVISION DATE BY COMMENTS
//** <revision number> <date> <author> <comments about the
change>
//**
//** ARGUMENTS: <argument description>
//**
//** RETURNED VALUE: < description of possible return values>
//**
//**
NOTE: The order of functions in a file is important. Initialisation and shutdown functions should be
placed at the top of the file. Command functions should be next. Local utility functions
should be at the bottom of the file.

For example ;
//** FUNCTION : OpenRecipeDatabase
//**
//** DESCRIPTION : Opens the specified database.
//**
//** REVISION DATE BY COMMENTS
//** 1 28/09/97 GM Original
//** 2 05/10/97 KD Added INI checking
//**
//** ARGUMENTS:
 Chapter 8 - Cicode Programming Standard 101

//**
//** STRING sName Name of the recipe database.
//**
//** INT dwMode Mode to open the recipe database.
//** 0 for read only, 1 for read/write.
//**
//** RETURNED VALUE: Handle if successful, otherwise -1.
//**
//** NOTES:

INT
FUNCTION
OpenRecipeDatabase(STRING sName, INT dwMode)

…
END

Modular Programming
The best way to solve a problem is to partition the problem into smaller, more manageable problems
and to solve these smaller problems. A similar approach should be taken when using a programming
language like Cicode to complete a task. Reducing the task to smaller tasks (or functions) has the
following advantages:

Reduced Complexity - Once the function is created and tested, the detailed operation about how it
works can be forgotten. Users need only be concerned with calling the function as they can be
assured the tested function will yield predictable results.

Avoids Duplicate Code - Creating a generic function instead of copying similar code reduces the
total amount of code in the system. It also means the function can be reused by separate code
areas. This makes the code more maintainable because it is smaller in size, and only one instance
needs to be modified.

Hides Information - Information can be in the form of operations, data, or resources. Access to
information can be controlled when functions are written that provide a limited set of actions to be
performed on the information. For example, if a user wishes to log a message to a database, he or
she should only send the message to a function, say LogDBaseMessage("hello world"), and the
function should control the database resource. The function then becomes the single interface to
the database resource. Resources that have multiple interfaces to them are harder to control. This
is because in a multitasking environment, the user cannot guarantee the order of code execution,
and hence a resource may be modified at the same time by different tasks. Information hiding can
also smooth out any wrinkles in standard functions, preventing possible misuse of resources such as
semaphores, queues, devices, and files. Functions that do this are often called ‘wrapper’ functions
as they add a protective shell to existing functions.
102 Modular Programming

Improves Performance - Optimising code that resides in one place immediately increases the
performance of code that calls this function. Scattered code will require all areas to be modified
should any optimisation be necessary.

Isolates Complex Code - Code that requires complex operations such communications protocols,
complex algorithms, boolean logic, or complex data manipulation is susceptible to errors. Placing
this code in a separate function reduces the possibility of this code corrupting or halting other code.

Improves Readability - A small function with meaningful parameter names assists readability as it
is a step towards self documenting code and eliminates the need to scan multiple pages of code to
establish what the operation is meant to achieve.
Modular Programming has a few rules that define how functions should be structured - Cohesion - and
how they are related to other functions - Coupling.

Cohesion

A goal of Modular Programming is to create simple functions that perform a single task, but perform
that task well. This can be described as how ‘cohesive’ a function is.
Two factors that affect the level of cohesion are:

Number of tasks the function performs

Similarity of the tasks
The following table illustrates the different levels of cohesion.
Number of tasks Similarity Cohesion Level Example
1 not applicable high Sin(x)
more than 1 similar moderate SinAndTan(x)
more than 1 dissimilar low SinAndLength(x)
many radically none SinAndDateAndTimeAndSQL
different Next(x)
For example, the function Sin(x) will perform one task - return the trigonometric Sine value of x. This
is an example of a highly cohesive function. The function SinAndTan(x) performs two tasks -
calculate the trigonometric Sine and Tan of the value X. This function has lower cohesion than Sin(x)
because it performs two tasks.
Highly cohesive function are more reliable, easier to modify, and easier to debug than functions that
have lower levels of cohesion and are hence acceptable and encouraged.
Low cohesion functions are typically complex, prone to errors, and are more costly to fix. Low
cohesion functions are regarded as unacceptable and discouraged.
 Chapter 8 - Cicode Programming Standard 103

Coupling

Another rule of Modular Programming is to reduce the number of relationships between functions.
This is referred to as function coupling. Functions that have few, or no, relationships between them
are loosely coupled. Loosely coupled functions provide simple, visible interfaces to the function. This
makes the functions easier to use and modify. For example, the Cicode function TimeCurrent() is a
loosely coupled function. To use this function, a user need only call its name, and the function will
return with the desired result. The user does not need to be aware of any relationships because there
are no parameters passed to the function, and it does not read from, or write to, any global data. Very
little can go wrong with this function; it only returns a time/date variable with no error codes to worry
about. In the unlikely event that the function fails, it would be through no fault of the calling function
because it has no relationship to it.
Functions that have many relationships between them are tightly coupled. For example, a user written
function like AddCustomerRecord(hDatabase, sFirstName, sSurname, sAddress, sAge, sPhone)
has a higher level of coupling than the function TimeCurrent(). Tightly coupled functions are
inflexible in their use, less robust, and harder to maintain. The AddCustomerRecord() function is
less robust because it could fail of its own accord, or fail if the function calling it passes bad data to it.
Tightly coupled functions are harder to maintain because modifying a function with many relationships
in it may result in modifications to other functions to accept the data.
The different types of function relationships are listed below:

Passed parameters. A simple, visible form of loose coupling that is encouraged. Once the
number of parameters passed to a function exceeds seven, you should consider partitioning the
function into two smaller functions. These types of relationships are acceptable.

Control information. Control information causes the called function to behave in a different way.
For example, the function ChangeData(iMode), behaves differently depending on the value of the
variable iMode that is passed into it. It may be responsible for deleting, inserting, or updating
data. In addition to being a tightly coupled function, it has low cohesion because it performs
multiple tasks. This function could be broken up into three separate functions to perform the
separate tasks. These types of relationships are moderately acceptable.

Shared common data. This is often referred to as global variable data. This is an invisible form
of tight coupling that, particularly in pre-emptive, multi-tasking environments, can be a hazardous
exercise. When functions write to the global variable data there is no guarantee as to who is
writing to the variable. Hence the value can be indeterminate. Global variables are acceptable
when they are used for read-only purposes, otherwise their use is discouraged. Similarly, module
variable data in Citect version 5.XX should be treated the same way. The use of local function
variables is encouraged to decrease function coupling.
It is very hard to write Cicode such that all your functions are loosely coupled with high levels of
cohesion. The time spent optimising your Cicode to conform completely to these programming
methodologies may be better spent elsewhere in your configuration. There are, however, acceptable
levels in these methodologies that should be adhered to. A good rule of thumb when programming is
to write functions in such a way that anybody can at least read and understand what you have done,
with the possibility that they could modify them without having to call you in the middle of the night.
104 Modular Programming

Cohesion and Coupling Examples

The example functions below indicate how tightly coupled module functions with low cohesion can be
written using shared common data and control information.

// Bad Module Example

INT ghDatabase; // global database handle
INT giRecordNumber; // global database record number
INT giAction; // global database function mode
STRING gsName; // global database record name
STRING gsNewName; // global database record new name

FUNCTION Customer()

ghDatabase = DevOpen("Customer",0);
GetActionAndRecordNumberAndName();

// the next function performs multiple tasks and operates on

global data,
// therefore it is tightly coupled and has low cohesion.
EditDatabase();

DevClose(giDatabase);

END // End Customer function

FUNCTION EditDatabase()

SELECT CASE giAction // control information, global data

CASE 1
DevSeek(ghDatabase, giRecordNumber);
DevDelete(ghDatabase);
CASE 2
DevSeek(ghDatabase, giRecordNumber);
DevSetField(ghDatabase, "Name", gsNewName);
CASE 3
DevAppend(ghDatabase);
DevSetField(ghDatabase, "Name", gsName);
END SELECT

END // End EditDatabase function

Following this is an example of loosely coupled, highly cohesive module functions. Note the use of
global variables as read-only constants as well as passed parameters to simple functions.

// Good Module Example with error checking in functions

INT ciDelete = 1; // global read-only variable or
constant
 Chapter 8 - Cicode Programming Standard 105

INT ciUpdate = 2; // global read-only variable or constant

INT ciInsert = 3; // global read-only variable or
constant
// note that this global data could have been created as Labels in
the Labels database

FUNCTION Customer()
INT iAction = 0;
STRING sName = "no name";
STRING sNewName = "no name";
STRING sDatabase = "Customer";

ErrSet(1); // stops code being halted on function

failure
iAction = GetActionFromUser();

SELECT CASE iAction

CASE ciDelete
sName = GetCustomerName("Customer name to Delete");
DeleteUser(sDatabase, sName);
CASE ciUpdate
sName = GetCustomerName("Customer name to Change");
sNewName = GetCustomerName("New name for Customer");
UpdateUser(sDatabase, sName, sNewName);
CASE ciInsert
sName = GetCustomerName("Customer name to Insert");
InsertUser(sDatabase, sName);
CASE ELSE
// invalid mode, prompt error
END SELECT

END // End Customer function

INT
FUNCTION DeleteUser(STRING sDatabase = "no database", STRING sName
= "no name")
INT iError = 0;
INT hDatabase = -1;

IF sDatabase = "no database" THEN

RETURN -1;
END

IF sName = "no name" THEN

RETURN -2;
END

hDatabase = DevOpen(sDatabase, 0);

IF hDatabase >= 0 THEN

106 Modular Programming

iError = DevFind(hDatabase, sName, "Name");

IF iError = 0 THEN
iError = DevDelete(hDatabase);
END
ELSE
// device not opened
RETURN -3;
END

DevClose(hDatabase);
RETURN iError;
END // End DeleteUser function

Defensive Programming

Always make sure that your code never produces unexplained Hardware Alarms.

Always check that denominators in division are not zero.

Always check that array indexes cannot go out of range.

Check that arguments from external sources are valid.

Check that loop terminations are obvious and always achievable.

Never write the same code twice. If you find that two sections of code look identical or almost
identical it is worth spending the time to re-write or re-design it. This will generally cut the size of
the code in question by a third or more, which reduces complexity and therefore maintenance and
debugging time. The most effective method to achieve this is to convert the identical code to a new
function.

Do not under any circumstance access the module data in any function other than the member
functions.

Write the member functions whenever an array is defined. Do not try to pass arrays between
functions, make the arrays the centre piece of the object.

Cicode is a multitasking language. Several tasks (commands, expressions and tasks created by
TaskNew function) can be executed concurrently. This powerful feature of Cicode should be used
with care as some of the functions may be modifying module data. It is essential that the number
of tasks running at any point in time be minimised. This may require the use of semaphores to
protect the module data from interference and corruption. (For the use of semaphores, refer to
SemOpen, SemClose, SemSignal and SemWait functions in on-line help or the Cicode Reference
manual).
 Chapter 8 - Cicode Programming Standard 107

Error handling
Errors are handled by examining the return values of the functions. The Cicode functions can be
classified as regards their return value as follows:
Functions returning Calling functions should check for

Error code only 0 no error (success)

>0 error code

Handles -1 bad handle

>= 0 valid handle

Random values the return of IsError()

The following Cicode functions can halt the current task:

DevOpen, DevHistory, DevNext, DevPrev, DevSeek, DevFind, DevFlush, DevRecNo, DevRead,
DevReadLn, DevAppend, DevDelete, DevZap, DevControl , DevPrint , DevModify;

ErrTrap;

FileOpen, FileClose, FileReadBlock, FileWriteBlock, FileSeek, FileDelete, FileReName, FileSize,
FileReadLn, FileCopy;

FormNew;

SQLConnect, SQLTraceOn, SQLTraceOff, SQLErrMsg.
If an error occurs in one of these functions, your Cicode task will generate a hardware error and be
halted. You may stop your Cicode task from being halted by using the ErrSet() function and checking
for errors using IsError().
The parameter [Code]HaltOnError allows you to stop any errors in these functions from halting your
Cicode. If you set. . .

[code]
HaltOnError=0
then your Cicode will continue to run after a hardware error in these functions.
For example:

Example of error code only
INT
FUNCTION
ExampleInit()

INT nError = 0;

nError = ExampleOpen("MyForm");
108 Error handling

IF nError = 0 THEN
.
.
.
END
END

INT
FUNCTION
ExampleOpen(STRING sName)

INT nError = 0;
.
.
IF <an error has occurred> THEN
nError = 299;
END
RETURN nError;
END

Example of handles

INT
FUNCTION
ExampleInit()

INT hFile = BAD_HANDLE;

…
hFile = ExampleFileOpen("MyFile.txt");
IF hFile <> BAD_HANDLE THEN
…
…
END
END

INT
FUNCTION
ExampleFileOpen(STRING sName)

INT hFile = BAD_HANDLE;

hFile = FileOpen(sName, "r+");

IF hFile = BAD_HANDLE THEN
hFile = FileOpen(sName, "r");
END

RETURN hFile;
END
 Chapter 8 - Cicode Programming Standard 109

Example of random values

INT
FUNCTION
ExampleInit()

INT nSamples = 0;
…
…
ErrSet(1);
nSamples = ExampleSamples();
IF IsError() = 0 THEN
…
…
END
ErrSet(0);
END

INT
FUNCTION
ExampleSamples()

INT nSamples = 0;
INT nError = 0;
…
…
ErrTrap(nError);

RETURN nSamples;
END

Debug Error Trapping

During the debugging stage of project development all the help one can get will be needed. The
methods described below can also be used during normal project execution in order to trap the run-
time problems.

The DebugMsg Function

The DebugMsg() function will internally call the TraceMsg() function if the debug switch is on. The
implementation of this function can be found in DEBUG.CI in the INCLUDE project. The debug
switch can be turned on and off either by:
110 Debug Error Trapping

Calling DebugMsgSet(INT bDebugMsg) function on the Kernel Cicode window. (Or, this function
can be called from a keyboard command or something similar.); or

Changing the [Code]DebugMessage parameter in the INI file.
For example:

INT
FUNCTION
FilePrint(STRING sDeviceName, STRING sFileName)

INT hFile;
INT hDev;
STRING Str1;

hDev = DevOpen(sDeviceName, 0);

IF (hDev = -1) THEN
DebugMsg("Invalid arg to FilePrint - 'DeviceName'");
RETURN 261; /* File does not exist */
END

hFile = FileOpen(sFileName, "r");

IF (hFile = -1) THEN
DebugMsg("Invalid arg to FilePrint - 'FileName'");
DevClose(hDev);
RETURN 261; /* File does not exist */
END

WHILE NOT FileEof(hFile) DO

Str1 = FileReadLn(hFile);
DevWriteLn(hDev, Str1);
END

FileClose(hFile);
DevClose(hDev);
RETURN 0;
END

The Assert Function

The Assert function will report an error if the test passed by the argument fails. The implementation of
this function can be found in DEBUG.CI in the INCLUDE project.
For Example:

INT
FUNCTION
FileDisplayEx(STRING sFileName)
 Chapter 8 - Cicode Programming Standard 111

INT hFile;

hFile = FileOpen(sFileName, "r");

ASSERT(hFile <> -1);
.
.
FileClose(hFile);
RETURN 0;
END
 113

Part B
Function Categories
 Chapter 9 - Function Categories

ActiveX Functions

ActiveX functions enable you to create and interact with ActiveX objects, using Citect as an ActiveX
container.
_ObjectCallMethod Calls a specific method for an ActiveX object.
_ObjectGetProperty Retrieves a specific property of an ActiveX object.
_ObjectSetProperty Sets a specific property of an ActiveX object.
AnByName Retrieves the animation point number of an ActiveX object.
CreateControlObject Creates a new instance of an ActiveX object.
CreateObject Creates the automation component of an ActiveX object.
ObjectAssociateEvents Allows you to change the ActiveX object’s event class.
ObjectAssociatePropertyWithTag Establishes an association between a variable tag and an
ActiveX object property.
ObjectByName Retrieves an ActiveX object.

Alarm Functions
Alarm functions display alarms and their related alarm help pages, and acknowledge, disable, and
enable alarms. They provide information about alarms and allow your operators to add comments to
alarm records. You can also access alarms at the record level (on the Alarms Server) for more
complex operations.
AlarmAck Acknowledges alarms.
AlarmAckRec Acknowledges alarms by record number.
AlarmActive Determines if any alarms are active in the user's area.
AlarmClear Clears acknowledged, inactive alarms from the active alarm list.
AlarmClearRec Clear an alarm by it's record number.
AlarmComment Allows users to add comments to alarm summary entries.
AlarmDelete Deletes alarm summary entries.
AlarmDisable Disables alarms.
AlarmDisableRec Disables alarms by record number.
116 Alarm Functions

AlarmDsp Displays alarms.

AlarmDspLast Displays the most recent, unacknowledged alarms.
AlarmDspNext Displays the next page of alarms.
AlarmDspPrev Displays the previous page of alarms.
AlarmEnable Enables alarms.
AlarmEnableRec Enables alarms by record number.
AlarmEventQue Opens the alarm event queue.
AlarmFirstCatRec Searches for the first occurrence of an alarm category and type.
AlarmFirstPriRec Searches for the first occurrence of an alarm priority and type.
AlarmFirstTagRec Searches for the first occurrence of an alarm tag, name, and description.
AlarmGetDsp Gets field information from an alarm entry displayed at an AN.
AlarmGetFieldRec Gets alarm field data from the alarm record number.
AlarmGetInfo Gets information about an alarm list displayed at an AN.
AlarmGetThreshold Gets the thresholds of analog alarms.
AlarmGetThresholdRec Gets the thresholds of analog alarms by the alarm record number.
AlarmHelp Displays the help page for the alarm where the cursor is positioned.
AlarmNextCatRec Searches for the next occurrence of an alarm category and type.
AlarmNextPriRec Searches for the next occurrence of an alarm priority and type.
AlarmNextTagRec Searches for the next occurrence of an alarm tag, name, and description.
AlarmSetInfo Changes the display parameters for the alarm list displayed at an AN.
AlarmSetQuery Specifies a query .to be used in selecting alarms for display.
AlarmSetThreshold Changes the thresholds of analog alarms.
AlarmSetThresholdRec Changes the thresholds of analog alarms by the alarm record number.
AlarmSplit Duplicates an alarm summary entry where the cursor is positioned.
AlarmSumAppend Appends a new blank record to the alarm summary.
AlarmSumCommit Commits the alarm summary record to the alarm summary device.
AlarmSumDelete Deletes alarm summary entries.
AlarmSumFind Finds an alarm summary index for an alarm record and alarm on time.
AlarmSumFirst Gets the oldest alarm summary entry.
AlarmSumGet Gets field information from an alarm summary entry.
AlarmSumLast Gets the most recent 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.
 Alarm Functions 117

Clipboard Functions
With the clipboard functions, you can copy data to, and paste data from, the Windows clipboard.
ClipCopy Copies a string to the Windows clipboard.
ClipPaste Pastes a string from the Windows clipboard.
ClipReadLn Reads a line of text from the Windows clipboard.
ClipSetMode Sets the format of data sent to the Windows clipboard.
ClipWriteLn Writes a line of text to the Windows clipboard.

Cluster Functions
ClusterGetName Returns the names of the primary and standby cluster servers to which Citect
is currently connected.
ClusterSetName Connects to a specific cluster server.

Colour Functions
Allow manipulation of colours (e.g. to convert Citect colours to the format required by ActiveX
objects).
CitectColourToPackedRGB Converts a Citect colour into a packed RGB colour value that can be used by
an ActiveX object.
GetBlueValue Returns the Blue component of a packed RGB colour.
GetGreenValue Returns the Green component of a packed RGB colour.
GetRedValue Returns the Red component of a packed RGB colour.
PackedRGB Returns a packed RGB colour based on specified red, green, and blue values.
PackedRGBToCitectColour Converts a packed RGB colour into the nearest equivalent Citect colour.

Communication Functions
With the Communication functions, you have direct access to the communication ports on your
computer(s). You can use these functions to communicate with external equipment, such as low
118 Communication Functions

speed devices (e.g. bar code readers), serial keyboards, and dumb terminals. You should not use these
functions to communicate with high speed PLCs, because the performance may not be adequate.

NOTE: The Communication functions can only be called from an I/O Server.

ComClose Closes a communication port.

ComOpen Opens a communication port for access.
ComRead Reads characters from a communication port.
ComReset Resets the communication port.
ComWrite Writes characters to a communication port.
SerialKey Redirects all serial characters from a port to the keyboard.

DDE Functions
The DDE (Dynamic Data Exchange) functions allow you to exchange data between Citect and other
Windows applications in real time, continuously, and with no operator intervention. For example, you
can send your run-time data to a spreadsheet calculator or word processing package, either by posting
the data to memory for access by other applications, or by writing the data directly into another
application. Conversely, you can read data from a spreadsheet or document into a Citect variable.
You can run processes in any Windows application by using the DDEExec() function to send commands to
that application. Similarly, you can call any Cicode function (in-built or user-
written) in Citect from any Windows application that supports a DDE Execute
command. (See Using DDE for details of how DDE works.)
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 - all in one operation.
The DDE handle (DDEh...) functions return a handle to the conversation - a DDE channel number.
You should use the DDE handle functions for Network DDE, in particular for Access DDE.
DDEExec Executes a command in an external Windows application.
DDEPost Makes a Citect variable available for DDE linking by other Windows
applications.
DDERead Reads a variable from a Windows application.
DDEWrite Writes a variable to a Windows application.
DDEhExecute Executes a command in an external Windows application.
DDEhGetLastError Gets the most recent Windows error code.
DDEhInitiate Starts a DDE conversation with an external Windows application.
DDEhPoke Writes data to a Windows application.
DDEhReadLn Reads a line of text from a DDE Conversion.
 DDE Functions 119

DDEhRequest Requests data from a Windows application.

DDEhSetMode Set the mode of a DDE conversation.
DDEhTerminate Closes a DDE conversation with a Windows application.
DDEhWriteLn Writes a line of text to the DDE conversation.

Device Functions
The Device functions provide extensive access to Devices. They allow access to SQL, dBASE, and
ASCII files through database-like operations, and provide more control over output to printers.

With these functions you can open and close any device, and read from and write to any record or
field in the device. You can store recipes or any other data in a database, and then down-load or up-
load the data as required to an I/O Device on the plant floor, or to the operator. You can also update
the database with real-time data for data exchange with other applications.
DevAppend Appends a blank record to the end of a device.
DevClose Closes a device.
DevControl Controls a dBASE or SQL device.
DevCurr Gets the current device number.
DevDelete Deletes the current record in a database device.
DevDisable Disables (and re-enables) a device from any access.
DevEOF Checks for the end of a file.
DevFind Finds a record in a device.
DevFirst Finds the first record in a device.
DevFlush Flushes buffered data to a device.
DevGetField Gets field data from the current record.
DevHistory Renames a device file and any subsequent history files.
DevInfo Gets device information.
DevNext Gets the next record in a device.
DevModify Modifies the attributes of a device.
DevOpen Opens a device for access.
DevPrev Gets the previous record in a device.
DevPrint Prints free-format data to a group of devices.
DevRead Reads characters from a device.
DevReadLn Reads a line of characters from a device.
DevRecNo Gets the current record number of a device.
DevSeek Moves to any record in a device.
DevSetField Sets new field data in the current record.
120 Device Functions

DevSize Gets the size of a device.

DevWrite Writes a string to a device.
DevWriteLn Writes a string with a newline character to a device.
DevZap Zaps a device.
Print Prints a string in a report.
PrintLn Prints a string with a newline character in a report.
PrintFont Changes the printing font on the current device.

Display Functions
Display functions control the display and processing of graphics pages and objects. With these
functions you can display graphics pages, print them on your printer, send them to a file, or copy them
to the Windows clipboard. You can also display text files on the screen.

NOTE: The properties defined for an object will override any conflicting Cicode Display functions.

You can create and move ANs (animation-point numbers), and obtain runtime information about
graphics pages and their associated ANs.
DspAnCreateControlObject Creates a new instance of an ActiveX object. If the object already exists for
the given Animation Point Number, then that object will be used (a new object
is not created).
DspAnFree Frees (removes) an AN from the current page.
DspAnGetArea Gets the area configured for an object at a specific AN (animation-point
number).
DspAnGetPos Gets the x and y coordinates of an AN (animation-point number).
DspAnGetPrivilege Gets the privileges configured for an object at a specific AN (animation-point
number).
DspAnInfo Gets information on the state of the animation at an AN.
DspAnInRgn Checks if an AN is within a specified region.
DspAnMove Moves an AN.
DspAnMoveRel Moves an AN relative to its current position.
DspAnNew Creates an AN.
DspAnNewRel Creates an AN relative to another AN.
DspBar Displays a bar graph at an AN.
DspBmp Displays a bitmap at a specified AN.
DspButton Displays a button at an AN and puts a key into the key command line (when
the button is selected).
DspButtonFn Displays a button at an AN and calls a function when the button is selected.
 Display Functions 121

DspChart Displays a chart at an AN.

DspCol Displays a colour at an AN.
DspDel Deletes all objects at an AN.
DspDelayRenderBegin Delays screen updating until DspDelayRenderEnd() is called.
DspDelayRenderEnd Ends the screen update delay set by DspDelayRenderBegin().
DspDirty Forces an update to an AN.
DspError Displays an error message at the prompt AN.
DspFile Defines the screen attributes for displaying a text file.
DspFileGetInfo Gets the attributes of a file to screen display.
DspFileGetName Gets the name of the file being displayed in the display "window".
DspFileScroll Scrolls a file (displayed in the display "window") by a number of characters.
DspFileSetName Sets the name of the file to display in the display "window".
DspFont Creates a font.
DspFontHnd Gets a font handle.
DspFullScreen Enables or disables the full screen mode of the active window.
DspGetAnBottom Gets the bottom extent of the object at the specified AN.
DspGetAnCur Gets the current AN.
DspGetAnExtent Gets the extent of the object at a specified AN.
DspGetAnFromPoint Gets the AN of the object at a specified set of screen coordinates.
DspGetAnHeight Gets the height of the object at a specified AN.
DspGetAnLeft Gets the left extent of the object at the specified AN.
DspGetAnRight Gets the right extent of the object at the specified AN.
DspGetAnTop Gets the top extent of the object at the specified AN.
DspGetAnWidth Gets the width of the object at a specified AN.
DspGetEnv Gets a page environment variable.
DspGetMouse Gets the mouse position.
DspGetNearestAn Gets the nearest AN.
DspGetParentAn Gets the parent animation number (if any), for the specified AN.
DspGetSlider Gets the current position (value) of a slider at an AN.
DspGetTip Gets the tool tip text associated with an AN.
DspGrayButton Greys and disables a button.
DspInfo Gets object display information from an AN.
DspInfoDestroy Deletes an object information block created by DspInfoNew().
DspInfoField Gets stored and real-time data for a variable tag.
DspInfoNew Creates an object information block for an AN.
DspInfoValid Checks if an object information block is still valid.
DspIsButtonGray Gets the current status of a button.
122 Display Functions

DspKernel Displays the Kernel window.

DspMarkerMove Moves a trend or chart marker to a specified position.
DspMarkerNew Creates a new trend marker.
DspMCI Controls a multimedia device.
DspPlaySound Plays a waveform (sound).
DspRichText Creates a Rich Text object at the animation point.
DspRichTextEdit Enables/disables editing of the contents of a rich text object.
DspRichTextEnable Enables/disables a rich text object.
DspRichTextGetInfo Returns size information about a rich text object.
DspRichTextLoad Loads a copy of a rich text file into a rich text object.
DspRichTextPgScroll Scrolls the contents of a rich text object by one page length.
DspRichTextPrint Prints the contents of a rich text object.
DspRichTextSave Saves the contents of a rich text object to a file.
DspRichTextScroll Scrolls the contents of a rich text object by a user defined amount.
DspRubEnd Ends a rubber band selection.
DspRubMove Moves a rubber band selection to the new position.
DspRubSetClip Sets the clipping region for the rubber band display.
DspRubStart Starts a rubber band selection (used to rescale a trend with the mouse).
DspSetSlider Sets the current position of a slider at the specified AN.
DspSetTip Sets tool tip text associated with an AN.
DspSetTooltipFont Sets the font for tool tip text.
DspStatus Sets the communication status error for a specified animation number.
DspStr Displays a string at an AN.
DspSym Displays a symbol at an AN.
DspSymAnm Displays a series of animated symbols at an AN.
DspSymAnmEx Displays a series of animated symbols at an AN.
DspSymAtSize Displays a symbol at a scale and offset from an AN.
DspText Displays text at an AN.
DspTipMode Switches the display of tool tips on or off.
DspTrend Displays a trend at an AN.
DspTrendInfo Gets information on a trend definition.
 DLL Functions 123

DLL Functions
The DLL (Dynamic Link Library) functions allow you to call any DLL, including the Windows
standard functions, any third-party library, or your own library.

With the DLL functions, you can write functions in 'C', Pascal, or any other language that supports
DLLs, and then call those functions from Citect.
DLLCall Calls a DLL function.
DLLClose Closes a link to a DLL function.
DLLOpen Opens a link to a DLL function.

Error Functions
The Error functions trap and process errors. You can use Error functions to check the status of any
other function.
ErrCom Gets the communication status for the current Cicode task.
ErrDrv Gets a protocol-specific error message.
ErrGetHw Gets a hardware error code.
ErrHelp Displays help information about a hardware error.
ErrInfo Gets error information.
ErrLog Logs a system error.
ErrMsg Gets the error message associated with a hardware error.
ErrSet Sets the error mode.
ErrSetHw Sets a hardware error.
ErrSetLevel Sets the error level.
ErrTrap Generates an error trap.
IsError Checks for an error.

Event Functions
The Event functions trap and process asynchronous events.
CallEvent Calls the event function for an event type.
ChainEvent Calls an event function, by function number.
GetEvent Gets the function number of the current callback event.
OnEvent Sets an event callback function, by event type.
124 Event Functions

SetEvent Sets an event callback function, by function number.

File Functions
The File functions provide access to standard ASCII files. You can open or create files and then read
and write data in free format. Use these functions when you require more complex file operations
than are possible with the Device functions; e.g. importing and exporting data to and from other
programs (that support ASCII files).

You can build complex I/O functionality by combining these functions with the Format functions.
FileClose Closes a file.
FileCopy Copies a file or group of files.
FileDelete Deletes a file.
FileEOF Checks for the end of a file.
FileExist Checks if a file exists.
FileFind Finds a file that matches a specified search criteria.
FileGetTime Gets the time on a file.
FileMakePath Creates a file path string from individual components.
FileOpen Opens or creates an ASCII file.
FilePrint Prints a file on a device.
FileRead Reads characters from a file.
FileReadBlock Reads a block of characters from a file.
FileReadLn Reads a line from a file.
FileRename Renames a file.
FileRichTextPrint Prints a rich text file.
FileSeek Seeks a position in a file.
FileSetTime Sets the time on a file.
FileSize Gets the size of a file.
FileSplitPath Splits a file path into individual string components.
FileWrite Writes characters to a file.
FileWriteBlock Writes a block of characters to a file.
FileWriteLn Writes a line to a file.
 Form Functions 125

Form Functions
Form functions create and display data entry forms. Use them when you want to display large
amounts of data or request data from the operator, for example, to display, load, and/or edit a database
of recipes.
FormActive Checks if a form is currently active.
FormAddList Adds a text string to a list box or combo box.
FormButton Adds a button to a form.
FormCheckBox Adds a check box to the current form.
FormComboBox Adds a combo box to the current form.
FormCurr Gets the current form and field handles.
FormDestroy Removes a form from the screen.
FormEdit Adds edit fields to a form.
FormField Adds general fields to a form.
FormGetCurrInst Gets data associated with a field.
FormGetData Gets all data associated with a form.
FormGetInst Gets data associated with a field on a form.
FormGetText Gets field text on an active form.
FormGoto Go to a specified form.
FormGroupBox Adds a group box to the current form.
FormInput Adds an input field to a form.
FormListAddText Adds a new text entry to a combo box or a list box.
FormListBox Adds a list box to the current form.
FormListDeleteText Deletes existing text from combo box or list box.
FormListSelectText Selects (highlights) a text entry in a combo box or a list box.
FormNew Creates a new form.
FormNumPad Provides a keypad form for the operator to add numeric values.
FormOpenFile Displays a File Open dialog box.
FormPassword Adds an password (no echo) input field.
FormPosition Sets the position of a form on the screen, before it is displayed.
FormPrompt Adds a prompt to a form.
FormRadioButton Adds a radio button to the current form.
FormRead Displays a form and reads user input.
FormSaveAsFile Displays a File Save As dialog box.
FormSelectPrinter Displays the Select Printer dialog box.
FormSetData Sets data in a form.
FormSetInst Associates data to a field on a form.
126 Form Functions

FormSetText Sets field text on an active form.

FormWndHnd Gets the window handle for the given form.

Format Functions
Format functions convert data into formatted strings. You can convert many different items of data
into single, formatted strings that can then be displayed, printed, or written to a file. The Format
functions also convert (formatted) data back into individual elements, e.g. strings that are read from
files or other devices.
FmtClose Closes a format template.
FmtFieldHnd Gets the handle of a field in a format template.
FmtGetField Gets field data from a format template.
FmtGetFieldHnd Gets field data from a format template using a field handle.
FmtOpen Creates a new format template.
FmtSetField Sets data in a field of a format template.
FmtSetFieldHnd Sets data in a field of a format template using a field handle.
FmtToStr Converts format template data to a string.

FTP Functions
FTP functions are used to manage your FTP communications and files (used when running your
project over the Internet). These functions can only be used on the Internet Display Client.
FTPClose Closes an FTP session.
FTPFileCopy Copies a file from the FTP server to the Internet Display Client.
FTPFileFind Finds a file on the FTP server that matches a specified search criteria.
FTPOpen Connects to an FTP server.

FuzzyTech Functions
The Citect FuzzyTech functions provide support for fuzzy logic control. These Cicode functions
provide an interface to the FuzzyTech functions provided by INFORM Software Corporation. To use
these functions you must purchase the development environment from INFORM - the makers of
FuzzyTech.
FuzzyClose Closes specified fuzzy instance.
FuzzyGetCodeValue Gets a specified Code variable from the specified instance.
 FuzzyTech Functions 127

FuzzyGetShellValue Gets a specified Shell variable from the specified instance.

FuzzyOpen Creates a new fuzzy instance.
FuzzySetCodeValue Sets a specified Code variable in the specified instance.
FuzzySetShellValue Sets a specified Shell variable in the specified instance.
FuzzyTrace Controls the tracing.

Super Genie Functions

The Super Genie functions allow you to use Super Genies in your runtime system.
Ass Associates a variable tag with a Super Genie.
AssChain Chains the associations from the current Super Genie to a new Super
Genie.
AssChainPage Chains the associations from the current Super Genie to a new Super
Genie, and displays the new Super Genie (in the current window).
AssChainPopUp Chains the associations from the current Super Genie to a new Super
Genie, and displays the new Super Genie in a new popup window.
AssChainWin Chains the associations from the current Super Genie to a new Super
Genie, and displays the new Super Genie in a new window. The new
window will be of the same type as the current window.
AssChainWinFree Saves the tag associations on an existing Super Genie, closes it, then
assigns the tags to a new window.
AssInfo Gets association information about the current Super Genie (i.e.
information about a variable tag that has been substituted into the 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.
AssScaleStr Gets scale information about the associations of the current Super Genie
(i.e. scale information about a variable tag that has been substituted into
the Super Genie).
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.
AssTitle Sets the runtime window title to the tag name of the first variable
substituted into the Super Genie.
AssVarTags Associates up to eight variable tags with a Super Genie. This
association is only made for the next Super Genie you display (either in
128 Super Genie Functions

the current window or in a new window). You can use this function
repeatedly 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.

Group Functions
Group functions manipulate groups of areas, alarm categories, and any other data that can be accessed
as a group. With these functions, you can create a group dynamically and use the group for a variety
of purposes; for example, to allow operators to change their areas, or to view alarms by category, etc.
GrpClose Closes a group.
GrpDelete Deletes items from a group.
GrpFirst Gets the first item in a group.
GrpIn Tests if an item is in a group.
GrpInsert Inserts items into a group.
GrpMath Performs mathematical operations on groups.
GrpName Gets the name of a group from a group handle.
GrpNext Gets the next item in a group.
GrpOpen Opens a group.
GrpToStr Converts a group into a string.

I/O Device Functions

The I/O Device functions allow you to read the values of variables in I/O Devices such as PLCs, and
to write data into these I/O Device variables. These functions also allow you to control I/O Devices
and to display information about I/O Devices.
IODeviceControl Provides control of individual I/O Devices.
IODeviceInfo Gets information on an I/O Device.
IODeviceStats Gets statistical information for all I/O Devices.
TagDebug Displays a dialog which allows you to select any configured tag to read or
change (write) its value.
TagInfo Gets information about a variable tag.
TagRamp Increments a tag by a percentage amount.
TagRead Reads a variable from an I/O Device.
TagScaleStr Gets the value of a tag at a specified scale.
TagWrite Writes to an I/O Device variable.
 Keyboard Functions 129

Keyboard Functions
Keyboard functions control the processing of keyboard entries, including the movement of the
keyboard cursor and the manipulation of keyboard commands.
KeyAllowCursor Allows the command cursor to move to any AN or only to ANs that have
commands defined.
KeyBs Deletes the last character from the key command line.
KeyDown Moves the command cursor down.
KeyGet Gets the raw key code from the key command line.
KeyGetCursor Gets the AN where the cursor is positioned.
KeyLeft Moves the command cursor left.
KeyMove Moves the command cursor in the required direction.
KeyPeek Gets a key from the key command line without removing the key.
KeyPut Puts a raw key code into the key command line.
KeyPutStr Puts a string into the key command line.
KeyReplay Replays the last key sequence.
KeyReplayAll Replays and executes the last key sequence.
KeyRight Moves the command cursor right.
KeySetCursor Moves the command cursor to a specified AN.
KeySetSeq Adds a keyboard sequence at runtime.
KeyUp Moves the command cursor up.
SendKeys Sends a keystroke (or string of keystrokes) to a window.

Mail Functions
The mail facility enables you to send data (e.g. a report) between Citect users (or any other computer).
Citect can send mail automatically, triggered by an event such as a report or an alarm. Citect can also
read mail, so any user on the system can send mail to Citect (for example, a batch recipe).
You can use the mail facility to send information from Citect to Managers, Supervisors or anyone on a
LAN or WAN whether they are running Citect or not. You can use Citect to send mail directly to
these people whenever an event occurs (for example, you can mail reports directly to the QA
department when they are scheduled, or send mail to the maintenance department when equipment is
due for service).
The mail system uses the MAPI standard interface, so you can use any mail system that supports this
standard. The mail system allows data transfer across different computer platforms and to remote
sites (using a data gateway), enabling you to send high-level data across a wide area network.
MailError Gets the last mail error code.
130 Mail Functions

MailLogoff Logoff from the mail system.

MailLogon Logon to the mail system.
MailRead Reads a standard mail message.
MailSend Sends a standard mail message.

Math/Trig Functions
Abs Gets the absolute value of a number.
ArcCos Gets the arccosine of an angle.
ArcSin Gets the arcsine of an angle.
ArcTan Gets the arctangent of an angle.
Cos Gets the cosine of an angle.
DegToRad Converts an angle from degrees to radians.
Exp Raises e to the power of a number.
Fact Gets the factorial of a number.
HighByte Gets the high-order byte of a two-byte integer.
HighWord Gets the high-order word of a four-byte integer.
Ln Gets the natural logarithm of a number.
Log Gets the base 10 logarithm of a number.
LowByte Gets the low-order byte of a two-byte integer.
LowWord Gets the low-order word of a four-byte integer.
Max Gets the higher of two numbers.
Min Gets the lower of two numbers.
Pi Gets the value of pi.
Pow Raises a number to the power of another number.
RadToDeg Converts an angle from radians to degrees.
Rand Gets a random number.
Round Rounds a number.
Sign Gets the sign of a number.
Sin Gets the sine of an angle.
Sqrt Gets the square root of a number.
Tan Gets the tangent of an angle.
 Miscellaneous Functions 131

Miscellaneous Functions
AccControl Controls accumulators e.g. motor run hours.
AreaCheck Determines whether the current user has access to a specified area.
Assert Verifies a particular condition is true, or halts the task.
Beep Beeps the speaker or sound card in the computer.
CitectInfo Gets information about a Citect variable.
CodeTrace Traces Cicode into the Kernel and the SYSLOG.DAT file.
DebugBreak Causes a breakpoint error to start the Cicode Debugger.
DebugMsg In-line debug messages of user Cicode.
DebugMsgSet Enables/disables the DebugMsg function.
DumpKernel Dumps Kernel data to the Kernel.dat file.
EngToGeneric Converts a variable into generic scale format.
Exec Executes an application or PIF file.
GetArea Gets the current viewable areas.
GetEnv Gets an environment variable.
InfoForm Displays graphics object help information for the AN closest to the cursor.
InfoFormAn Displays graphics object help information for an AN.
Input Gets text input from the operator.
IntToReal Converts an integer variable into a real (floating point) number.
KerCmd Executes a command in a kernel window.
LanguageFileTranslate Translates an ASCII file into the local language.
Message Displays a message box on the screen.
ParameterGet Gets the value of a system parameter.
ParameterPut Updates a system parameter.
ProjectRestartGet Gets the path to the project to be run the next time Citect is restarted.
ProjectRestartSet Sets the path to the project to be run the next time Citect is restarted.
ProjectSet Sets the name or path of the current project.
Prompt Displays a message in the prompt line.
Pulse Pulses (jogs) a variable tag every two seconds.
ServerInfo Gets client and server information.
SetArea Sets the current viewable areas.
SetLanguage Sets the current language for runtime text, and the character set.
Shutdown Ends Citect's operation.
ShutdownForm Displays a form that allows an operator to shut down the Citect system.
ShutdownMode Gets the mode of the shutdown/restart.
SwitchConfig Switches focus to the Citect configuration application.
132 Miscellaneous Functions

TestRandomWave Generates a random wave.

TestSawWave Generates a saw wave.
TestSinWave Generates a sine wave.
TestSquareWave Generates a square wave.
TestTriangWave Generates a triangular wave.
Toggle Toggles a digital tag on or off.
TraceMsg Displays a message in the Kernel and Debugger debug windows.
Version Gets the version number of the Citect software.

Page Functions
Page functions display graphics pages, files, and the standard alarm, trend, and menu pages.
PageAlarm Displays a category of active alarms on the predefined alarms page.
PageDisabled Displays a category of disabled alarms on the predefined alarms page.
PageDisplay Displays a graphics page.
PageFile Displays a file on the predefined file to screen page.
PageFileInfo Returns the width or height of an unopened page in pixels.
PageGetInt Gets a local page-based integer.
PageGetStr Gets a local page-based string.
PageGoto Displays a graphics page without pushing the last page onto the PageLast
stack.
PageHardware Displays the active hardware alarms on the predefined alarms page.
PageInfo Gets page information.
PageLast Displays the last ten graphics pages.
PageMenu Displays a menu page with page selection buttons.
PageNext Displays the next graphics page.
PagePeekLast Gets any page on the PageLast stack.
PagePopLast Gets the last page on the PageLast stack.
PagePopUp Displays the pop up window at the mouse position.
PagePrev Displays the previous graphics page.
PagePushLast Puts a page on the end of the PageLast stack.
PageRichTextFile Used as a page entry function - creates a rich text object, and loads a rich text
file into that object.
PageSelect Displays a dialog box with a list of graphics pages defined in the project.
PageSetInt Stores a local page-based integer.
PageSetStr Stores a local page-based string.
 Page Functions 133

PageSummary Displays a category of alarm summary entries on the predefined alarm page.
PageTrend Displays a standard trend page.

Plot Functions
With the plot functions, you can plot system data on the screen or on your system printer(s).
PlotClose Displays and/or prints the plot, then closes the plot.
PlotDraw Draws a point, line, box, or circle on a plot.
PlotFile This function is now obsolete.
PlotGetMarker Gets the marker number of a symbol that is registered as a marker.
PlotGrid Draws gridlines to be used for plotted lines.
PlotInfo Gets information about a plot.
PlotLine Plots a line through a set of data points.
PlotMarker Draws markers on a plotted line or at a specified point.
PlotOpen Opens a new plot, sets its output device, and returns a plot handle for use by
the other plot functions.
PlotScaleMarker Draws scale lines (with markers) beside the grid on your plot (if there is one).
PlotSetMarker Sets (registers) a symbol as a marker.
PlotText Draws text on a plot.
PlotXYLine Draws an XY line through a set of data points.

Report Functions
With the Report functions, you can run reports on the report server, change their scheduling, or get
their status.
RepGetControl Gets report control information.
Report Runs a report.
RepSetControl Sets report control information.
134 Security Functions

Security Functions
The Security functions allow you to control logins, logouts, and general security, and to add, delete,
and modify user records during run time. By giving selected users access to these functions, you can
provide them with supervisory control of the system.
FullName Gets the full name of the current operator.
GetPriv Checks the privilege and area of the current operator.
Login Logs an operator into the Citect system.
LoginForm Displays a form that allows an operator to log in to the Citect system.
Logout Logs an operator out of the Citect system.
LogoutIdle Sets an idle time logout for the current operator.
Name Gets the user name of the current operator.
UserCreate Creates a new user record during run time.
UserCreateForm Displays a form to create a record for a new user.
UserDelete Deletes a new user record during run time.
UserEditForm Displays a form for a selected user to create or delete user records during run
time.
UserPassword Changes a user's password during run time.
UserPasswordForm Displays a form for the operator to change their own password during run
time.
UserInfo Gets information about the operator who is currently logged-in to the system.
WhoAmI Displays the name of the operator who is currently logged-in to the system.

SPC Functions
SPC (Statistical Process Control) functions allow you to alter the properties and parameters that affect
the SPC calculations. By using the SPC functions you may also gain direct access to the SPC data
and alarms.
SPCAlarms Returns the status of the specified SPC alarm.
SPCClientInfo Returns SPC data for the given SPC tag.
SPCGetHistogramTable Returns an array containing the frequency of particular ranges for the given
SPC tag.
SPCGetSubgroupTable Returns an array containing the specified subgroup's elements with the mean,
range and standard deviation.
SPCPlot Generates a single page print showing three separate trends of the SPC Mean,
Range, and Standard Deviation.
SPCProcessXRSGet Gets the process mean, range and standard deviation overrides.
 SPC Functions 135

SPCProcessXRSSet Sets the process mean, range and standard deviation overrides.
SPCSetLimit Sets the upper or lower control limits of X-bar, range, or standard deviation
charts.
SPCSpecLimitGet Gets the specification limits (USL and LSL) for the specified tag.
SPCSpecLimitSet Sets the specification limits (USL and LSL) for the specified tag.
SPCSubgroupSizeGet Gets the size of a subgroup for the specified SPC tag.
SPCSubgroupSizeSet Sets the subgroup size for the specified SPC tag.

SQL Functions
SQL (Structured Query Language) functions allow you to define, manipulate, and control data in SQL
databases and other relational databases. By using the SQL functions (or the Device functions with an
SQL device), you have direct access to data on database servers, mini-computers, and mainframe
computers.

ExecuteDTSPkg Loads and executes a DTS package which initiates data transfer between OLE
DB data sources.
SQLAppend Appends a text string to the SQL buffer.
SQLBeginTran Starts a database transaction.
SQLCommit Commits a transaction to the database.
SQLConnect Makes a connection to a database system for execution of SQL statements.
SQLDisconnect Closes a database connection.
SQLEnd Terminates an SQL query.
SQLErrMsg Returns an error message from the SQL system.
SQLExec Executes an SQL query on a database.
SQLFieldInfo Gets information about the fields or columns selected in an SQL query.
SQLGetField Gets field or column data from a database record.
SQLInfo Gets information about a database connection.
SQLNext Gets the next database record from a SQL query.
SQLNoFields Gets the number of fields or columns that were returned by the last SQL
statement.
SQLNumChange Gets the number of records that were modified in the last insert, update, or
delete SQL statement.
SQLRollBack Rolls back (or cancels) the last database transaction.
SQLSet Sets a statement string in the SQL buffer.
SQLTraceOff Turns off the debug trace.
SQLTraceOn Turns on the debug trace.
136 String Functions

String Functions
String functions allow you to manipulate strings in various ways. You can extract characters or sub-
strings from a string, convert strings into other data types, format strings, search for strings, and
perform various other operations.
CharToStr Converts an ASCII code into a string.
HexToStr Converts a number into a hexadecimal string.
IntToStr Converts an integer variable into a string.
PathToStr Converts a Citect path into a string.
RealToStr Converts a floating-point variable into a string.
StrClean Removes control characters from a string.
StrFill Fills a string with characters.
StrFormat Formats a variable into a string.
StrGetChar Gets a single character from a string or buffer.
StrLeft Gets the left-most characters from a string.
StrLength Gets the length of a string.
StrLower Converts a string to lower-case.
StrMid Gets characters from the middle of a string.
StrPad Pads a string to the required length.
StrRight Gets the right-most characters from a string.
StrSearch Searches for a string within a string.
StrSetChar Sets a single character into string or buffer.
StrToChar Converts a string to an ASCII code.
StrToDate Converts a string into a date variable.
StrToFmt Converts a string into format fields.
StrToGrp Converts a string into a group.
StrToHex Converts a hexadecimal string into an integer.
StrToInt Converts a string into an integer variable.
StrToLocalText Converts a string from Native language to Local language.
StrToPeriod Converts a string into a (time) period.
StrToReal Converts a string into a floating-point variable.
StrToTime Converts a string into a time variable.
StrToValue Converts a string into a floating-point variable.
StrTrim Trims spaces from a string.
StrUpper Converts a string to upper-case.
StrWord Gets a word from a string.
 Table (Array) Functions 137

Table (Array) Functions

Table functions perform mathematical functions on entire tables (or arrays), such as the calculation of
minimum, maximum, average, and standard deviation values.
TableLookup Gets a value from a table.
TableMath Performs mathematical operations on a table, e.g. average, maximum,
minimum, etc.
TableShift Shifts a table, left or right.

Task Functions
Task functions support advanced multi-tasking operations in Cicode, handling queues, semaphores,
messages, and other process functions. The Task functions control the transfer of data between
different Cicode tasks and across the network to different computers (by remote procedure calls).
CodeSetMode Sets the execution mode of a Cicode task.
EnterCriticalSection Requests permission for the current thread to have access to a critical
shared resource (critical section). If the critical section is already being
accessed, the thread will be granted access when it is free.
Halt Halts the current Cicode task.
LeaveCriticalSection Relinquishes the current thread's ownership of a critical shared resource
(critical section).
MsgBrdcst Broadcasts a message.
MsgClose Closes a message.
MsgGetCurr Gets the handle of the message that called the current report or remote
procedure.
MsgOpen Opens a message session to a Citect server or client.
MsgRead Reads a message from a session.
MsgRPC Calls a remote procedure on another Citect computer.
MsgWrite Writes a message to a session.
QueClose Closes a queue.
QueLength Gets the current length of a queue.
QueOpen Creates or opens a queue.
QuePeek Searches a queue for a queue element.
QueRead Reads elements from a queue.
QueWrite Writes elements to a queue.
ReRead Causes Citect to re-read the I/O Device data associated with the current
Cicode task.
138 Task Functions

SemClose Closes a semaphore.

SemOpen Creates or opens a semaphore.
SemSignal Signals a semaphore.
SemWait Waits on a semaphore.
Sleep Suspends the current Cicode task for a specified time.
SleepMS Suspends the current Cicode task for a specified time (in milliseconds).
TaskGetSignal Retrieves a value that indicates the stop signal for a specific task.
TaskHnd Gets the handle of a particular task.
TaskKill Kills a running task.
TaskNew Creates a new task.
TaskResume Resumes a task.
TaskSetSignal Ends a task by manually triggering its stop signal.
TaskSuspend Suspends a task.

Time/Date Functions

Time/Date functions manipulate time and date variables. Citect stores time/date-related variables as a
single integer. This integer represents the number of seconds since 01/01/1970. It is in GMT, but it
has an offset that updates it to local time (determined by the timezone the application is in). The
Time/Date functions convert this integer into time and date variables.
IMPORTANT: The Time/Date functions can only be used with dates between 1980 and 2035.

Date Gets the current system date in string format.

DateAdd Adds time to a date.
DateDay Gets the day from a date.
DateMonth Gets the month from a date.
DateSub Subtracts two dates.
DateWeekDay Gets the day of week from a date.
DateYear Gets the year from a date.
SysTime Marks the start of an event.
SysTimeDelta Calculates the time-span of an event.
Time Gets the current system time in string format.
TimeCurrent Gets the current time/date value.
TimeHour Gets hours from a time.
TimeMidNight Converts a time variable into the time at midnight.
 Time/Date Functions 139

TimeMin Gets minutes from a time.

TimeSec Gets seconds from a time.
TimeSet Sets the new system time on the computer.
TimeToStr Converts a time/date variable into a string.

Trend Functions
You can control all aspects of a trend's operation with the Trend functions. Citect has standard trend
pages, so you would not normally use these low-level functions unless you want to define your own
trend displays. You can control the movement of the trend cursor, trend scaling, and the definition of
trend attributes (such as the trend starting time and sampling period). You can also create, and
subsequently delete trends.
TrnAddHistory Restores an old history file to the trend system.
TrnClientInfo Gets information about the trend that is being displayed at the AN point.
TrnComparePlot Prints two trends (one overlaid on the other), each with up to four trend tags.
TrnDelete Deletes a trend created by the TrnNew() function.
TrnDelHistory Deletes an old history file from the trend system.
TrnEcho Enables and disables the echo on the trend display.
TrnEventGetTable Stores event trend data and the associated time stamp in an event table and
time table, for a specified trend tag.
TrnEventGetTableMS Stores event trend data and time data (including milliseconds) for a specified
trend tag.
TrnEventSetTable Sets trend data from a table, for a specified trend tag.
TrnEventSetTableMS Sets event trend data and time data (including milliseconds) for a specified
trend tag.
TrnExportClip Exports trend data to the clipboard.
TrnExportCSV Exports trend data to a file in CSV (comma separated values) format.
TrnExportDBF Exports trend data to a file in dBASE III format.
TrnExportDDE Exports trend data to applications via DDE.
TrnFlush Flushes the trend to disk.
TrnGetBufEvent Gets the event number of a trend at an offset for a pen.
TrnGetBufTime Gets the trend time at an offset for a pen.
TrnGetBufValue Gets the trend value at an offset for a pen.
TrnGetCursorEvent Gets the event number of a trend at the trend cursor.
TrnGetCursorMSTime Gets the time (in milliseconds from the previous midnight) at a trend cursor
for a specified pen.
TrnGetCursorPos Gets the position of the trend cursor.
140 Trend Functions

TrnGetCursorTime Gets the time/date at the trend cursor.

TrnGetCursorValue Gets the current trend cursor value of a pen.
TrnGetCursorValueStr Gets the current trend cursor value of a pen as a formatted string.
TrnGetDefScale Gets the default engineering zero and full scales of a trend tag.
TrnGetDisplayMode Gets the display mode of a trend.
TrnGetEvent Gets the event number of a trend at a percentage along the trend.
TrnGetFormat Gets the format of a pen.
TrnGetGatedValue Returns the internally stored value for <GATED>.
TrnGetInvalidValue Returns the internally stored value for <TRN_NO_VALUES>.
TrnGetMode Gets the display mode of trends (historical or real-time).
TrnGetMSTime Gets the time (in milliseconds from the previous midnight) of the trend
(plotted by a specified pen) at a percentage along the trend, using the time and
date of the right-most sample displayed.
TrnGetPen Gets the trend tag of a pen.
TrnGetPenFocus Gets the number of the pen currently in focus.
TrnGetPenNo Gets the pen number of a pen name.
TrnGetPeriod Gets the display period of a trend.
TrnGetScale Gets the scale of a pen.
TrnGetScaleStr Gets the scale of a pen as a formatted string.
TrnGetSpan Gets the span time of a trend.
TrnGetTable Stores trend data in an array.
TrnGetTime Gets the time/date of a pen.
TrnGetUnits Gets the data units of a trend pen.
TrnInfo Gets the configured values of a trend tag.
TrnIsValidValue Determines whether a logged trend value is <VALID>, <GATED>, or invalid
<TRN_NO_VALUES>.
TrnNew Creates a new trend at run time.
TrnPlot Prints a plot of one or more trend tags.
TrnPrint Prints a trend that is displayed on the screen.
TrnSamplesConfigured Gets the number of samples configured for the currently displayed trend.
TrnScroll Scrolls a trend pen.
TrnSelect Sets up a page for a trend.
TrnSetCursor Moves the trend cursor a specified number of samples.
TrnSetCursorPos Moves the trend cursor to the given x-axis position.
TrnSetDisplayMode Specifies how trend samples will be displayed on the screen.
TrnSetEvent Sets the start event of a trend pen.
TrnSetPen Sets a trend pen to a new trend tag.
 Trend Functions 141

TrnSetPenFocus Sets the pen focus.

TrnSetPeriod Sets the display period (time base) of a trend.
TrnSetScale Re-scales a pen.
TrnSetSpan Sets the span time of a trend.
TrnSetTable Sets trend data from an array.
TrnSetTime Sets the starting time/date of a pen.
The following trend functions are used on all standard trend templates. You should only use these
functions if you create your own trend templates. (These functions are written in Cicode and can be
found in the include project.)
TrendDspCursorScale Displays a scale value for the current pen.
TrendDspCursorTag Displays the tag name of the current pen.
TrendDspCursorTime Displays the cursor time of the current pen.
TrendDspCursorValue Displays the cursor value of the current pen.
TrendGetAn Gets the AN number of the trend under the mouse position.
TrendPopUp Displays a pop-up trend with the specified trend pens.
TrendRun Initialises the cursor and rubber-band features on a trend page.
TrendSetDate Sets the starting date for all the pens on a trend.
TrendSetScale Sets the scale of one or more pens on a trend.
TrendSetSpan Sets the span time of a trend.
TrendSetTime Sets the starting time for all the pens on a trend.
TrendSetTimeBase Sets a new sampling period for a trend.
TrendWin Displays a trend page (in a new window) with the specified trend pens.
TrendZoom Zooms a trend in either one or both axes.

Window Functions
Window functions control the display of windows. You can open, move, size, activate, and de-
activate windows. You can also specify titles for your windows.
WinCopy Copies the active window to the Windows clipboard.
WinFile Writes the active window to a file.
WinFree Removes a display window.
WinGetFocus Gets the number of the Citect window that has the keyboard focus.
WinGetWndHnd Gets the window handle for the current window.
WinGoto Changes the active window.
WinMode Sets the display mode of the active window.
WinMove Moves the active window.
142 Window Functions

WinNew Opens a display window.

WinNewAt Opens a display window at specified coordinates.
WinNext Makes the next window active.
WinNumber Gets the window number of the active Citect window.
WinPos Positions a window on the screen.
WinPrev Makes the previous window active.
WinPrint Prints the active window.
WinPrintFile Prints a file to the printer.
WinSelect Selects a window for Cicode output.
WinSize Sizes a window.
WinTitle Sets the title of the active window.
WndFind Gets the Windows number of any window in any application.
WndGetFileProfile Gets a profile string from any .INI file.
WndGetProfile Gets WIN.INI parameters.
WndHelp Invokes the Windows Help application.
WndInfo Gets the Windows system metrics information.
WndPutFileProfile Puts a profile string into any .INI file.
WndPutProfile Updates WIN.INI parameters.
WndShow Sets the display mode of any window of any application.
WndViewer Invokes the Windows Multimedia application.
 143

Part C
Functions Reference
 Abs 145

_ObjectCallMethod
Description Calls a specific method for an ActiveX object. (Please refer to the documentation for your
ActiveX object for further details on its methods and properties.)

NOTE: The parameter list passed to the control can only have Cicode variables or variable tags; it cannot use values
returned directly from a function because an ActiveX control may modify parameters passed to it.

For example:

//Calculate a value and pass to ActiveX control

_ObjectCallMethod(hControl, "DoSomething" CalcValue());
is not allowed because the return value of a function cannot be modified. The following should be used instead:

INT nMyValue;
//Calculate Value
nMyValue = CalcValue();
//Pass Value to ActiveX control
_ObjectCallMethod(hControl, "DoSomething" nMyValue);
Syntax _ObjectCallMethod(hObject, sMethod, vParameters)

hObject ............The handle for the object (as returned by the ObjectByName() function).

sMethod ...........The name of the method.

vParameters.....A variable length parameter list of method arguments. The variables will be
passed however you enter them, and will then be coerced into appropriate
automation types. Likewise, any values modified by the automation call will be
written back - with appropriate coercion - into the passed Cicode variable.

Return Value The return value from the method - if successful, otherwise an error is returned.
Related Functions ObjectByName(),DspAnCreateControlObject(),CreateObject(),CreateControlObject()
Examples See CreateControlObject().

_ObjectGetProperty
Description Gets a specific property of an ActiveX object.
Syntax _ObjectGetProperty(hObject, sProperty)

hObject ............The handle for the object (as returned by the ObjectByName() function).

sProperty .........The name of the property you wish to get.

146 _ObjectGetProperty

Return Value The value of the property - if successful, otherwise an error is returned.
Related Functions ObjectByName(),DspAnCreateControlObject(),CreateObject(),CreateControlObject()
Examples See CreateControlObject().

_ObjectSetProperty
Description Sets a specific property of an ActiveX object.
Syntax _ObjectSetProperty(hObject, sProperty, vValue)

hObject............ The handle for the object (as returned by the ObjectByName() function).

sProperty.........The name of the property you wish to set.

vValue .............The value to which the property will be set. This value can be of any data type.
Appropriate coercion will take place when creating the equivalent automation
parameter.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ObjectByName(),DspAnCreateControlObject(),CreateObject(),CreateControlObject()
Examples See CreateControlObject().

Abs
Description Calculates the absolute (positive) value of a number. The absolute value of a number is the
number without its sign.
Syntax Abs(Number)

Number............ Any number.

Return Value The absolute (positive) value of Number.

Related Functions Sign
Examples
Variable=Abs(-67);
! Sets Variable to 67.

Variable=Abs(67);
! Sets Variable to 67.
 AccControl 147

AccControl
Description Controls accumulators, e.g. motor run hours. You can reset the values of Run Time, Totaliser
Inc, and No. of Starts (defined in the Accumulator database), re-read these values from the I/O
Device, or flush pending writes of these values to the I/O Device.
Syntax AccControl(sName, nMode)

sName ..............The name of the accumulator or a mask for the names of accumulators. You can
use the following wildcards:

*..... matches all following characters, e.g. "Motor*"

? ..... matches any character, e.g. "Motor?10".

nMode..............The mode of the control:

1 ..... Reset Run Time and Totaliser value

2 ..... Reset No. of Starts
3 ..... Reset Run Time, Totaliser value, and No. of Starts
4 ..... Flush pending writes to the I/O Device
5 ..... Re-read Run Time, Totaliser value, and No. of Starts from the I/O Device

Return Value 0 (zero) if successful, otherwise an error is returned.

Examples
! Reset all accumulator variables for accumulator "MCC123".
AccControl("MCC123", 3);

AlarmAck
Description Acknowledges alarms. You can acknowledge the alarm where the cursor is positioned, one or
more alarm lists on the active page, a whole category of alarms, or alarms of a particular priority.
You would normally call this function from a keyboard command. No action is taken if the
specified alarms have already been acknowledged.
Syntax AlarmAck(Mode, Value)

Mode................The type of acknowledgment:

0 ..... Acknowledge a single alarm where the cursor is positioned.

Set Value to 0 (zero) - it is not used.
148 AlarmAck

1 ..... Acknowledge a page of alarms. An alarm page can contain more than one
alarm list:
Set Value to the AN where the alarm list is displayed.
Set Value to 0 to acknowledge the (displayed) alarm list (on the active page)
where the cursor is positioned.
Set Value to -1 to acknowledge all (displayed) alarm lists on the active page.
2 ..... Acknowledge a category of alarms:
Set Value to the alarm category (0 to 255) of the alarms to be acknowledged.
Note that:
Alarm category 0 indicates all categories.
Alarm category 255 indicates hardware alarms.
Set Value to the group number to acknowledge a group of categories.
3 ..... Acknowledge alarms of a specific priority.
Set Value to the alarm priority (0-255) of the alarms to be acknowledged.

NOTE: .......Alarm priority 0 indicates all priorities.

....... Hardware alarms are not affected by priority.
....... Set Value to the group handle to acknowledge a group of alarms of
different priorities.

Value ...............Used with Mode 1 and 2 to specify which alarms to acknowledge.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen
Examples

System Keyboard
Key Sequence LeftButton

Command AlarmAck(0, 0)

Comment Acknowledge the alarm where the cursor

is positioned
 AlarmAck 149

System Keyboard
Key Sequence ShiftLeftButton

Command AlarmAck(1, -1)

Comment Acknowledge a page of alarms

System Keyboard
Key Sequence AlarmAck ### Enter

Command AlarmAck(2, Arg1)

Comment Acknowledge all alarms of a specified

category

System Keyboard
Key Sequence AckPri ############# Enter

Command AlarmAck(3,Arg1)
Comment Acknowledge all alarms of a specific
priority

! Acknowledge all alarms of the specified group of categories.

FUNCTION
AckGrp(STRING CategoryGroup)
INT hGrp;

hGrp=GrpOpen("CatGroup",1);
StrToGrp(hGrp,CategoryGroup);
AlarmAck(2,hGrp);
GrpClose(hGrp);
END
150 AlarmAckRec

AlarmAckRec
Description Acknowledges alarms by record number on both the Primary and Standby Alarms Servers. You
can call this function only on an Alarms Server. However, a client can call this function
remotely by using the MsgRPC() function.
Syntax AlarmAckRec(Record)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmFirstCatRec, AlarmFirstTagRec, AlarmNextCatRec, AlarmNextTagRec, AlarmGetDsp,
MsgRPC
Examples
/* Acknowledge all unacknowledged (Type 1) alarms of the specified alarm
category. */
FUNCTION
AutoAccept(INT Category)
INT Current;
INT Next;

Current=AlarmFirstCatRec(Category,1);
WHILE Current<>-1 DO
Next=AlarmNextCatRec(Current,Category,1);
AlarmAckRec(Current);
Current=Next;
END
END
 AlarmActive 151

AlarmActive
Description Determines if any alarms are active in the user's area. Call this function from the Page Strings
database, to display an alarm message at a specified AN on a graphics page. You can specify the
type of alarms, for example, active hardware alarms or disabled non-hardware alarms.
Syntax AlarmActive(Type)

Type .................The type of alarms to check:

Non-hardware alarms
0 ..... Active alarms
1 ..... Unacknowledged alarms, ON and OFF
3 ..... Disabled alarms
Hardware alarms
5 ..... Active alarms
6 ..... Unacknowledged alarms, ON and OFF

Return Value
1or 0 for Non-hardware alarms (modes 0, 1, and 3).

The number of active alarms for Hardware alarms (modes 5 and 6).
Examples

Strings
AN 9

Expression AlarmActive(5)

True Text "Hardware Alarms Active"

True Text "No Active Hardware Alarms"

Comment Display the alarm status at AN 9

152 AlarmClear

AlarmClear
Description Clears an acknowledged (and off) alarm from the active alarm list. You can clear the alarm
where the cursor is positioned, one or more alarm lists on the active page, a whole category of
alarms, or alarms of a particular priority.
If you set the [Alarm]AckHold parameter to 1, alarms that go off and have been acknowledged
are not removed from the active list until this function is called.
Syntax AlarmClear(Mode, Value)

Mode ...............The type of clear:

0 ..... Clear a single alarm where the cursor is positioned.

Set Value to 0 (zero) - it is not used.
1 ..... Clear a page of alarms. An alarm page can contain more than one alarm
list:
Set Value to the AN where the alarm list is displayed.
Set Value to 0 to clear the (displayed) alarm list (on the active page) where the
cursor is positioned.
Set Value to -1 to clear all (displayed) alarm lists on the active page.
2 ..... Clear a category of alarms.
Set Value to the alarm category (0 to 255) of the alarms to clear. Note that:
Alarm category 0 indicates all categories.
Alarm category 255 indicates hardware alarms.
Set Value to the group number to clear a group of categories.
3 ..... Clear alarms of a specific priority.
Set Value to the alarm priority (0-255) of the alarms to be cleared.

NOTE: .......Alarm priority 0 indicates all priorities.

....... Hardware alarms are not affected by priority.
....... Set Value to the group handle to clear a group of alarms of different
priorities.

Value ...............Used with Mode 1 or 2 to specify which alarms to clear.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmAck
 AlarmClear 153

Examples

System Keyboard
Key Sequence Clear
Command AlarmClear(0, 0)

Comment Clear the alarm where the cursor is

positioned

System Keyboard
Key Sequence ClearAll

Command AlarmClear(1, -1)

Comment Clear a page of alarms

System Keyboard
Key Sequence AlarmClear ### Enter

Command AlarmClear(2, Arg1)

Comment Clear all alarms of a specified category

System Keyboard
Key Sequence CtrlClear

Command AlarmClear(2, 0)

Comment Clear all categories of inactive alarms

154 AlarmClear

System Keyboard
Key Sequence ClearPri ########### Enter

Command AlarmClear(3,Arg1)

Comment Clear all alarms of a specific priority

AlarmClearRec
Description Clears an alarm by it's record number on both the Primary and Standby Alarms Servers. You
can call this function only on an Alarms Server. However, a client can call this function
remotely by using the MsgRPC() function.
Syntax AlarmClearRec(Record)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmAck, AlarmFirstCatRec, AlarmFirstTagRec, AlarmNextCatRec, AlarmNextTagRec,
AlarmGetDsp MsgRPC
 AlarmComment 155

AlarmComment
Description Allows an operator to add a comment to a selected alarm summary entry during runtime. You
would normally call this function from a keyboard command.
Comments can only be added to alarm summary (Alarm Type 10) alarms.
Syntax AlarmComment(sComment)

sComment ........The comment to add to the alarm summary entry. Comments have a maximum
of 128 characters.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmDsp
Examples

System Keyboard
Key Sequence Com ################## Enter

Command AlarmComment(Arg1)

Comment Add an alarm comment to the alarm

where the cursor is positioned

AlarmDelete
Description Deletes alarm summary entries that are currently displayed. You can delete the alarm where the
cursor is positioned, one or more alarm lists on the active page, a whole category of alarms, or
alarms of a particular priority.
You would normally call this function from a keyboard command.
Syntax AlarmDelete(Mode, Value)

Mode................The type of deletion:

0 ..... Delete a single alarm where the cursor is positioned.

Set Value to 0 (zero) - it is not used.
1 ..... Delete a page of alarms. An alarm page can contain more than one alarm
list:
156 AlarmDelete

Set Value to the AN where the alarm list is displayed.

Set Value to 0 to delete the (displayed) alarm list (on the active page) where the
cursor is positioned.
Set Value to -1 to delete all (displayed) alarm lists on the active page.
2 ..... Delete a category of alarms.
Set Value to the alarm category (0-255) of the alarms to delete. Note that:
Alarm category 0 indicates all categories.
Alarm category 255 indicates hardware alarms.
Set Value to the group number to delete a group of categories.
3 ..... Delete alarms of a specific priority.
Set Value to the alarm priority (0-255) of the alarms to be deleted.

NOTE: .......Alarm priority 0 indicates all priorities.

....... Hardware alarms are not affected by priority.
....... Set Value to the group handle to delete a group of alarms of different
priorities.

Value ...............Used with Mode 1 or 2 to specify which alarms to delete.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen
Examples

System Keyboard
Key Sequence DelSum

Command AlarmDelete(0, 0)

Comment Delete the alarm summary entry where

the cursor is positioned
 AlarmDelete 157

System Keyboard
Key Sequence ShiftDelSum

Command AlarmDelete(1, -1)

Comment Delete a page of alarm summary entries

System Keyboard
Key Sequence SumDelete ### Enter

Command AlarmDelete(2, Arg1)

Comment Delete all alarm summary entries of a

specified category

System Keyboard
Key Sequence DelSum ############# Enter

Command AlarmDelete(3,Arg1)
Comment Delete all alarm summary entries of a
specified priority

AlarmDisable
Description Disables alarms. You can disable the alarm where the cursor is positioned, one or more alarm
lists on the active page, a whole category of alarms, or alarms of a particular priority.
You would normally call this function from a keyboard command. No action is taken if the
alarms are already disabled. Use the AlarmEnable() function to re-enable an alarm.
After you disable an alarm, it does not display on the alarm page, alarm summary page, or alarm
log. If you set the [Alarm]DisplayDisable parameter to 1, logging of disabled alarms continues,
but the disabled alarms are not displayed on the alarm display or alarm summary pages.
Syntax AlarmDisable(Mode, Value)

Mode................The type of disable:

0 ..... Disable a single alarm where the cursor is positioned.

158 AlarmDisable

Set Value to 0 (zero) - it is not used.

1 ..... Disable a page of alarms. An alarm page can contain more than one alarm
list:
Set Value to the AN where the alarm list is displayed.
Set Value to 0 to disable the (displayed) alarm list (on the active page) where the
cursor is positioned.
Set Value to -1 to disable all (displayed) alarm lists on the active page.
2 ..... Disable a category of alarms.
Set Value to the alarm category (0-255) of the alarms to be disabled. Note that:
Alarm category 0 indicates all categories.
Alarm category 255 indicates hardware alarms.
Set Value to the group number to disable a group of categories.
3 ..... Disable alarms of a specific priority.
Set Value to the alarm priority (0-255) of the alarms to be disabled.

NOTE: .......Alarm priority 0 indicates all priorities.

....... Hardware alarms are not affected by priority.
....... Set Value to the group handle to disable a group of alarms of different
priorities.

Value ...............Used with Mode 1 and 2 to specify which alarms to disable.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen, AlarmEnable, AlarmDisableRec
Examples

System Keyboard
Key Sequence Disable

Command AlarmDisable(0, 0)

Comment Disable the alarm where the cursor is

positioned
 AlarmDisable 159

System Keyboard
Key Sequence ShiftDisable

Command AlarmDisable(1, -1)

Comment Disable a page of alarms

System Keyboard
Key Sequence AlarmDisable ### Enter

Command AlarmDisable(2, Arg1)

Comment Disable all alarms of a specified category

System Keyboard
Key Sequence DisPri ############# Enter

Command AlarmDisable(3,Arg1)

Comment Disable all alarms of a specific priority

AlarmDisableRec
Description Disables alarms by record number on both the Primary and Standby Alarms Servers. You can
call this function only on an Alarms Server. However, a client can call this function remotely by
using the MsgRPC() function.
Syntax AlarmDisableRec(Record)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()orAlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()orAlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()or
AlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.
160 AlarmDisableRec

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmFirstCatRec, AlarmFirstTagRec, AlarmNextCatRec, AlarmNextTagRec, AlarmDisable,
MsgRPC
Examples
/* Disable/enable the specified "Pump" alarm. Flag determines whether
the alarm is disabled (Flag=0) or enabled (Flag=1). */
FUNCTION
DisablePumps(STRING sTag, INT Flag)
INT Current;
INT Next;

Current=AlarmFirstTagRec(sTag,"Pump","");
WHILE Current<>-1 DO
Next=AlarmNextTagRec(Current,sTag,"Pump","");
IF Flag=0 THEN
AlarmDisableRec(Current);
ELSE
AlarmEnableRec(Current);
END
Current=Next;
END
END

AlarmDsp
Description Displays an alarm list, starting at a specified AN and then on subsequent ANs. You specify the
number of alarms to display and the type of alarms, for example, active hardware alarms or
disabled non-hardware alarms. Before you call this function, you must first add animation points
to the graphics page for each alarm to be displayed.
If you only need to display the standard alarm page, use the PageAlarm() function - it uses this
AlarmDsp() function to display alarms. If you need more control over the display of alarms you
can use this function, but only to display alarms on the alarm page. Use the AlarmDspLast()
function to display alarms on another graphics page (it uses less memory).
Syntax AlarmDsp(AN, Count, Type)

AN ...................The AN where the first alarm is to display.

 AlarmDsp 161

Count ...............The number of alarms to display.

Type .................The type of alarms to display:

Non-hardware alarms
0 ..... All active alarms, i.e. Types 1 and 2
1 ..... All unacknowledged alarms, ON and OFF
2 ..... All acknowledged ON alarms
3 ..... All disabled alarms
4 ..... All configured (non-hardware) alarms, i.e. Types 0 to 3, plus acknowledged
OFF alarms.
Hardware alarms
5 ..... All active alarms, i.e. Types 6 and 7
6 ..... All unacknowledged alarms, ON and OFF
7 ..... All acknowledged ON alarms
8 ..... All disabled alarms
9 ..... All configured alarms, i.e. Types 5 to 8
Alarm Summary
10.... All summary alarms
Alarm General
11.... All ON alarms
12.... All OFF alarms
13.... All ON hardware alarms
14.... All OFF hardware alarms
If you do not specify a Type, the default is 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmDspNext, AlarmDspPrev, AlarmDspLast, AlarmGetInfo, PageAlarm
Examples
162 AlarmDsp

Advanced Animation
Command AlarmDsp(20,15,3)

Comment Display 15 disabled alarms at AN 20

AlarmDspLast
Description Displays the most recent unacknowledged alarms, at a specified AN. Use this function to
display the last alarms on all (or selected) pages. You can specify the number of alarms to
display of a specified type, for example, active hardware alarms or disabled non-hardware
alarms.
Syntax AlarmDspLast(AN, Count, Type)

AN ...................The AN where the last alarms are to be displayed.

Count...............The number of alarms to display. If you do not specify a Count, the default is 1.

Type.................The type of alarms to display:

Non-hardware alarms
0 ..... All active alarms, i.e. Types 1 and 2
1 ..... All unacknowledged alarms, ON and OFF
2 ..... All acknowledged ON alarms
3 ..... All disabled alarms
4 ..... All configured (non-hardware) alarms, i.e. Types 0 to 3, plus acknowledged
OFF alarms.
Hardware alarms
5 ..... All active alarms, i.e. Types 6 and 7
6 ..... All unacknowledged alarms, ON and OFF
7 ..... All acknowledged ON alarms
8 ..... All disabled alarms
9 ..... All configured alarms, i.e. Types 5 to 8
Alarm Summary
10 ... All summary alarms
 AlarmDspLast 163

Alarm General
11.... All ON alarms
12.... All OFF alarms
13.... All ON hardware alarms
14.... All OFF hardware alarms
If you do not specify a Type, the default is 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmDsp
Examples

Advanced Animation
Command AlarmDspLast(11)

Comment Display the last alarm at AN 11

Advanced Animation
Command AlarmDspLast(21,3)

Comment Display the last 3 alarms at AN 21

AlarmDspNext
Description Displays the next page of alarms. This function pages down (scrolls) the alarms displayed by the
AlarmDsp() function. You would normally call this function from a keyboard command.
Syntax AlarmDspNext(AN)

AN....................The AN where the alarm list is displayed, or:

-1 .... Scroll all alarm lists displayed on the page.

0 ..... Scroll the alarm list where the cursor is positioned.
NOTE: An alarm page can contain more than one alarm list.

Return Value 0 (zero) if successful, otherwise an error is returned.

164 AlarmDspNext

Related Functions AlarmDsp, AlarmDspPrev

Examples

System Keyboard
Key Sequence NextAlarm

Command AlarmDspNext(20)

Comment Display the next page of alarms (from the

alarm list) at AN20

AlarmDspPrev
Description Displays the previous page of alarms. This function pages up (scrolls) the alarms displayed by
the AlarmDsp() function. You would normally call this function from a keyboard command.
Syntax AlarmDspPrev(AN)

AN ...................The AN where the alarm list is displayed, or:

-1.... Scroll all alarm lists displayed on the page.

0 ..... Scroll the alarm list where the cursor is positioned.
NOTE: An alarm page can contain more than one alarm list.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmDsp, AlarmDspNext
 AlarmDspPrev 165

Examples

System Keyboard
Key Sequence PrevAlarm
Command AlarmDspPrev(20)

Comment Display the previous page of alarms

(from the alarm list) at AN20

AlarmEnable
Description Enables an alarm on the active alarm list. You can enable the alarm where the cursor is
positioned, one or more alarm lists on the active page, a whole category of alarms, or alarms of a
particular priority.
No action is taken if the alarms are already enabled. You would normally call this function from
a keyboard command.
Syntax AlarmEnable(Mode, Value)

Mode................The type of enable:

0 ..... Enable a single alarm where the cursor is positioned.

Set Value to 0 (zero) - it is not used.
1 ..... Enable a page of alarms. An alarm page can contain more than one alarm
list:
Set Value to the AN where the alarm list is displayed.
Set Value to 0 to enable the (displayed) alarm list (on the active page) where the
cursor is positioned.
Set Value to -1 to enable all (displayed) alarm lists on the active page.
2 ..... Enable a category of alarms.
Set Value to the alarm category (0-255) of the alarms to be enabled. Note that:
Alarm category 0 indicates all categories.
Alarm category 255 indicates hardware alarms.
Set Value to the group number to enable a group of categories.
166 AlarmEnable

3 ..... Enable alarms of a specific priority.

Set Value to the alarm priority (0-255) of the alarms to be enabled.

NOTE: .......Alarm priority 0 indicates all priorities.

....... Hardware alarms are not affected by priority.
....... Set Value to the group handle to enable a group of alarms of different
priorities.

Value ...............Used with Mode 1 and 2 to specify which alarms to enable.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen, AlarmDisable, AlarmEnableRec
Examples

System Keyboard
Key Sequence Enable

Command AlarmEnable(0, 0)

Comment Enable the alarm where the cursor is

positioned

System Keyboard
Key Sequence ShiftEnable

Command AlarmEnable(1, -1)

Comment Enable a page of alarms

System Keyboard
Key Sequence AlarmEnable ### Enter

Command AlarmEnable(2, Arg1)

Comment Enable all alarms of a specified category

 AlarmEnable 167

System Keyboard
Key Sequence EnPri ############# Enter

Command AlarmEnable(3,Arg1)

Comment Enable all alarms of a specific priority

AlarmEnableRec
Description Enables alarms by record number on both the Primary and Standby Alarms Servers. You can
call this function only on an Alarms Server. However, a client can call this function remotely by
using the MsgRPC() function.
Syntax AlarmEnableRec(Record)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmFirstCatRec, AlarmFirstTagRec, AlarmNextCatRec, AlarmNextTagRec, AlarmEnable,
AlarmDisableRec, MsgRPC
Examples See AlarmDisableRec.
168 AlarmEventQue

AlarmEventQue
Description Opens the alarm event queue. The Alarms Server writes events into this queue as they are
processed. These events include all activated, reset, acknowledged, enabled and disabled alarms
To read events from this queue, use the QueRead() or QuePeek() functions. The data put into the
queue is the alarm record identifier (into the Type field) and the alarm event format (into the Str
field). The function puts all state changes into the queue and Citect does not use this queue for
anything.
To use this function, you must enable the alarm event queue with the [Alarm]EventQue
parameter. This parameter will tell the Alarms Server to start placing events into the queue. The
[Alarm]EventFmt parameter defines the format of the data placed into the string field. You can
enable the EventQue parameter without setting the event format to prevent the Alarms Server
from placing a formatted string into the queue. Enabling this feature can cause increase CPU
loading and reduce performance of the Alarms Server - only use this feature if really necessary.
The maximum length of each queue is controlled by the [Code]Queue parameter. You may need
to adjust this parameter so as not to miss alarm events. (When the queue is full, the Alarms
Server will discard events.)
Syntax AlarmEventQue()

Return Value The handle of the alarm event queue, or -1 if the queue cannot be opened.
Related Functions QueRead, QuePeek
Examples
hQue = AlarmEventQue()
WHILE TRUE DO
QueRead(hQue, nRecord, sAlarmFmt, 1);
/* do what ever with the alarm event */
....
Sleep(0);
END

AlarmFirstCatRec
Description Searches for the first occurrence of an alarm category and type. You can search all areas, the
current area only, or specify an area to limit the search. You can call this function only on an
Alarms Server. However, a client can call this function remotely by using the MsgRPC()
function.
This function returns an alarm record identifier that you can use in other alarm functions, for
example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm. To get
the alarm record identifier for an alarm on a Display Client, use the AlarmDspGet() function.
Syntax AlarmFirstCatRec(Category, Type, Area)
 AlarmFirstCatRec 169

Category ..........The alarm category or group number to match. Set Category to 0 (zero) to
match all alarm categories.

Type .................The type of alarms to find:

Non-hardware alarms
0 ..... All active alarms, i.e. Types 1 and 2.
1 ..... All unacknowledged alarms, ON and OFF.
2 ..... All acknowledged ON alarms.
3 ..... All disabled alarms.
4 ..... All configured alarms, i.e. Types 0 to 3, plus acknowledged OFF alarms.
If you do not specify a Type, the default is 0.

Area .................The area in which to search for alarms. If you do not specify an area, or if you
set Area to -1, only the current area will be searched.

Return Value The alarm record identifier or -1 if no match is found.

Related Functions GrpOpen, AlarmNextCatRec, AlarmFirstPriRec, AlarmNextPriRec, AlarmGetFieldRec,
AlarmAckRec, AlarmDisableRec, AlarmEnableRec, AlarmGetThresholdRec,
AlarmSetThresholdRec, MsgRPC
Examples See AlarmAckRec.

AlarmFirstPriRec
Description Searches for the first occurrence of an alarm priority and type. You can search all areas, the
current area only, or specify an area to limit the search. You can call this function only on an
Alarms Server. However, a client can call this function remotely by using the MsgRPC()
function.
This function returns an alarm record identifier that you can use in other alarm functions, for
example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm. To get
the alarm record identifier for an alarm on a Display Client, use the AlarmDspGet() function.
Syntax AlarmFirstPriRec(Priority, Type, Area)

Priority ............The alarm Priority or group handle of a group of alarm priorities. Set Priority to
0 (zero) to match all alarm priorities.

Type .................The type of alarms to find:

Non-hardware alarms
170 AlarmFirstPriRec

0 ..... All active alarms, i.e. Types 1 and 2.

1 ..... All unacknowledged alarms, ON and OFF.
2 ..... All acknowledged ON alarms.
3 ..... All disabled alarms.
4 ..... All configured alarms, i.e. Types 0 to 3, plus acknowledged OFF alarms.
If you do not specify a Type, the default is 0.

Area.................The area in which to search for alarms. Set Area to -1 to search all areas.

If you do not specify an area, only alarms in the current area on the Alarms
Server are searched.

Return Value The alarm record identifier or -1 if no match is found.

Related Functions GrpOpen, AlarmNextPriRec, AlarmFirstCatRec, AlarmNextCatRec, AlarmGetFieldRec,
AlarmAckRec, AlarmDisableRec, AlarmEnableRec, AlarmGetThresholdRec,
AlarmSetThresholdRec, AlarmSetInfo, MsgRPC
Examples
/* Acknowledge all unacknowledged (Type 1) alarms of the specified alarm
priority. */
FUNCTION
AutoAccept(INT iPriority)
INT iCurrent;
INT iNext;

iCurrent=AlarmFirstPriRec(iPriority,1,-1);
WHILE iCurrent <>-1 DO
iNext=AlarmNextPriRec(iCurrent,iPriority,1,-1);
AlarmAckRec(iCurrent);
iCurrent=iNext;
END
END

AlarmFirstTagRec
Description Searches for the first occurrence of an alarm tag, name, and description. You can only call this
function on an Alarms Server. However, a client can call this function remotely by using the
MsgRPC() function.
This function returns an alarm record identifier that you can use in other alarm functions, for
example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm.
Syntax AlarmFirstTagRec(Tag, Name, Description)
 AlarmFirstTagRec 171

Tag...................The alarm tag to be matched. Specify an empty string (" ") to match all alarm
tags.

Name................The alarm name to be matched. Specify an empty string (" ") to match all alarm
names.

Description ......The alarm description to be matched. Specify an empty string (" ") to match all
alarm descriptions.

Return Value The alarm record identifier or -1 if no match is found.

Related Functions AlarmNextTagRec, AlarmGetFieldRec, AlarmAckRec, AlarmDisableRec, AlarmEnableRec,
AlarmGetDsp, AlarmGetThresholdRec, AlarmSetThresholdRec, MsgRPC
Examples See AlarmDisableRec.

AlarmGetDsp
Description Gets field data from the alarm record that is displayed at the specified AN. You can use this
function for both Alarm Pages and Alarm Summaries (an Alarm Page or Alarm Summary must
be displayed before this function can be used).
You can call this function on an Alarms Server or a Display Client, to get the contents of any
field in the alarm record at that AN.
You can return the record number of the alarm record for use in other alarm functions, for
example, to acknowledge, disable, or enable an alarm (on an Alarms Server).
Syntax AlarmGetDsp(AN, sField)

AN....................The AN where the alarm entry is displayed.

sField ...............The name of the field from which the data is retrieved. The contents of the
following fields can be retrieved when either the Alarm Summary or the
Alarm Page is displayed:

Category .... Alarm category

Desc........... Alarm description
Help........... Alarm help page
Name ......... Alarm name
Tag ............ Alarm tag
Time .......... The time that the alarm changed state (hh:mm:ss)
OnTime ..... The time that the alarm was activated
172 AlarmGetDsp

RecNo ........The alarm record number

Comment ...Operator comments attached to the Alarm Log entry (if any)
The contents of the following fields can be retrieved only when the Alarm
Summary is displayed:
OnDate.......The date that the alarm was activated
OffDate ......The date that the alarm returned to its normal state
OffTime .....The time that the alarm returned to its normal state
DeltaTime ..The time difference between OnDate/OnTime and
OffDate/OffTime, in seconds
AckTime ....The time that the alarm was acknowledged
AckDate .....The date that the alarm was acknowledged
SumState ....Describes the state of the alarm when it occurred

Return Value Field data from the alarm entry (as a string).
Related Functions AlarmDsp
Examples
! Display the tag and category for the alarm at the specified AN.
FUNCTION
AlarmData(INT hAn)
STRING Category;
STRING Tag;

Category=AlarmGetDsp(hAn,"Category");
Tag=AlarmGetDsp(hAn,"Tag");
Prompt("Alarm "+Tag+" is Category "+Category);
END

AlarmGetFieldRec
Description Gets the contents of the specified field in the specified alarm record. This function can only be
called on an Alarms Server except in the following situations:

A client is calling this function remotely using the MsgRPC() function.

It is being used inside a query function on a display client
Additionally, this function can be called independently on a Display client, but will obtain
information only about alarms being displayed
Syntax AlarmGetFieldRec(Record, sField, nVer)
 AlarmGetFieldRec 173

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

sField ...............The name of the field from which the data is extracted. You can specify any of
the fields in any of the alarms databases (Digital Alarms, Analog Alarms, etc.).

Category .... Alarm category

Desc........... Alarm description
Help........... Alarm help page
Name ......... Alarm name
Tag ............ Alarm tag
Time .......... The time that the alarm changed state (hh:mm:ss)
OnTime ..... The time that the alarm was activated
RecNo ....... The alarm record number
Comment... Operator comments attached to the Alarm Log entry (if any)
OnDate ...... The date that the alarm was activated
OffDate ..... The date that the alarm returned to its normal state
OffTime..... The time that the alarm returned to its normal state
DeltaTime.. The time difference between OnDate/OnTime and
OffDate/OffTime, in seconds
AckTime ... The time that the alarm was acknowledged
AckDate .... The date that the alarm was acknowledged
SumState ... Describes the state of the alarm when it occurred

nVer .................The version of an alarm.

174 AlarmGetFieldRec

If an alarm has been triggered more than once in a given period, the version lets
you distinguish between different instances of the alarm's activity.
The version is used in filtering alarms for display. A query function passes a
value to this parameter in order to get field information for a particular alarm.
This parameter is not needed when you use AlarmGetFieldRec() for purposes
other than filtering. It will default to 0 if you do not set a value.

Return Value The alarm field data (as a string).

Related Functions AlarmFirstTagRec, AlarmFirstCatRec, AlarmNextTagRec, AlarmNextCatRec, MsgRPC
Examples
FUNCTION
GetNameFromTag(STRING sTag)
INT record;
STRING sName;

record = AlarmFirstTagRec(sTag, "", "");

IF record <> -1 THEN
sName = AlarmGetFieldRec(record,"NAME");
ELSE
sName = "";
END
RETURN sName;
END

AlarmGetInfo
Description Gets data on the alarm list displayed at a specified AN. Use this function to display the current
alarm list information on an alarm page. If only one alarm list has been configured on an alarm
page, modes 2 and 3 of this function return the current alarm page information.
Syntax AlarmGetInfo(AN, Type)

AN ...................The AN where the alarm list (with the required information) is displayed.

Set the AN to 0 (zero) to get information on the alarm list where the cursor is
positioned.

Type.................The type of data:

0 ..... Alarm page number. The vertical offset (in pages) from the AN where the
alarm list commenced. The alarm list must have scrolled off the first page
for this type to return a non-zero value.
 AlarmGetInfo 175

1 ..... Alarm list offset. The vertical offset (in lines) from the AN where the
alarm list commenced. You must have scrolled off the first page of alarms
for this type to return a non zero value.
2 ..... Category of alarms displayed on the alarm list. You can use a group
number to display a group of categories. This type should not be used if
more than one alarm list is configured for the page.
3 ..... Type of alarms displayed on the alarm list. See AlarmDsp() for a list of
these types. This type should not be used if more than one alarm list is
configured for the page.
7 ..... Priority of alarms displayed on the alarm list. The return value may be a
group number if the alarm list contains alarms of more than one priority.
8 ..... Alarm list display mode.
Set Value to 0 (zero) to display by Category.
Set Value to 1 to display by Priority.

Return Value Alarm list data from the alarm entry (as a string).
Related Functions AlarmDsp, AlarmSetInfo
Examples
/* In all of the following examples, data is returned on the alarm list
where the cursor is positioned. */
page = AlarmGetInfo(0,0);
! returns the alarm page number.
offset = AlarmGetInfo(0,1);
! returns the alarm list offset.
cat = AlarmGetInfo(0,2);
! returns the alarm category displayed.
type = AlarmGetInfo(0,3);
! returns the type of alarms displayed.

AlarmGetThreshold
Description Gets the threshold of the analog alarm where the cursor is positioned.
Syntax AlarmGetThreshold(Type)

Type .................The type of threshold:

0 ..... High high

1 ..... High
2 ..... Low
3 ..... Low low
176 AlarmGetThreshold

4 ..... Deadband
5 ..... Deviation
6 ..... Rate of change

Return Value The alarm threshold.

Related Functions AlarmGetThresholdRec, AlarmSetThreshold, AlarmSetThresholdRec

AlarmGetThresholdRec
Description Gets the threshold of analog alarms by the alarm record number. You can call this function only
on an Alarms Server for alarms on that server, or on the redundant server (if a redundant server
is configured). However, a client can call this function remotely by using the MsgRPC()
function.
Syntax AlarmGetThresholdRec(Record, Type)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Type.................The type of threshold:

0 ..... High high

1 ..... High
2 ..... Low
3 ..... Low low
4 ..... Deadband
5 ..... Deviation
 AlarmGetThresholdRec 177

6 ..... Rate of change

Return Value The alarm threshold.

Related Functions AlarmGetThreshold, AlarmSetThreshold, AlarmSetThresholdRec, MsgRPC

AlarmHelp
Description Displays the alarm help page (associated with the alarm) where the cursor is positioned. You
can assign a help page to each alarm when you define it (using the Digital Alarms or the Analog
Alarms database, depending on the type of alarm). You must also define the help page in the
Pages database.
Syntax AlarmHelp()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageAlarm
Examples

System Keyboard
Key Sequence AlmHelp

Command AlarmHelp()

Comment Display the alarm help page

AlarmNextCatRec
Description Searches for the next occurrence of an alarm category and type, commencing with the specified
alarm record identifier (returned from the previous search through the AlarmFirstCatRec()
function). You can search all areas, the current area only, or specify an area to limit the search.
You can call this function only on an Alarms Server. However, a client can call this function
remotely by using the MsgRPC() function.
This function returns an alarm record identifier that you can use in other alarm functions, for
example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm. To get
the alarm record identifier for an alarm on a Display Client, use the AlarmDspGet() function.
Syntax AlarmNextCatRec(Record, Category, Type, Area)
178 AlarmNextCatRec

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Category..........The alarm category or group number to match. Set Category to 0 (zero) to

match all alarm categories.

Type.................The type of alarms to find:

Non-hardware alarms
0 ..... All active alarms, i.e. Types 1 and 2.
1 ..... All unacknowledged alarms, ON and OFF.
2 ..... All acknowledged ON alarms.
3 ..... All disabled alarms.
4 ..... All configured alarms, i.e. Types 0 to 3, plus acknowledged OFF alarms.
If you do not specify a Type, the default is 0.

Area.................The area in which to search for alarms. If you do not specify an area, or if you
set Area to -1, only the current area will be searched.

Return Value The alarm record identifier or -1 if no match is found.

Related Functions GrpOpen, AlarmFirstCatRec, AlarmFirstPriRec, AlarmNextPriRec, AlarmGetFieldRec,
AlarmAckRec, AlarmDisableRec, AlarmEnableRec, AlarmGetThresholdRec,
AlarmSetThresholdRec, MsgRPC
Examples See AlarmAckRec.
 AlarmNextPriRec 179

AlarmNextPriRec
Description Searches for the next occurrence of an alarm of a specified priority and type, commencing with
the specified alarm record identifier (returned from the previous search through the
AlarmFirstPriRec() function). You can search all areas, the current area only, or specify an area
to limit the search. You can call this function only on an Alarms Server. However, a client can
call this function remotely by using the MsgRPC() function.
This function returns an alarm record identifier that you can use in other alarm functions, for
example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm. To get
the alarm record identifier for an alarm on a Display Client, use the AlarmDspGet() function.
Syntax AlarmNextPriRec(Record, Priority, Type, Area)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Priority ............The alarm Priority or group handle of a group of alarm priorities. Set Priority to
0 (zero) to match all alarm priorities.

Type .................The type of alarms to find:

Non-hardware alarms
0 ..... All active alarms, i.e. Types 1 and 2.
1 ..... All unacknowledged alarms, ON and OFF.
2 ..... All acknowledged ON alarms.
3 ..... All disabled alarms.
4 ..... All configured alarms, i.e. Types 0 to 3, plus acknowledged OFF alarms.
If you do not specify a Type, the default is 0.

Area .................The area in which to search for alarms. Set Area to -1 to search all areas.
180 AlarmNextPriRec

If you do not specify an area, only alarms in the current area on the Alarms
Server are searched.

Return Value The alarm record identifier or -1 if no match is found.

Related Functions GrpOpen, AlarmFirstPriRec, AlarmFirstCatRec, AlarmNextCatRec, AlarmGetFieldRec,
AlarmAckRec, AlarmDisableRec, AlarmEnableRec, AlarmGetThresholdRec,
AlarmSetThresholdRec, AlarmSetInfo, MsgRPC
Examples See AlarmFirstPriRec.

AlarmNextTagRec
Description Searches for the next occurrence of an alarm tag, name, and description, starting with the alarm
record identifier (returned from the previous search through the AlarmFirstTagRec() function).
You can call this function only on an Alarms Server. However, a client can call this function
remotely by using the MsgRPC() function.
This function returns an alarm record identifier that you can use in other alarm functions, for
example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm.
Syntax AlarmNextTagRec(Record, Tag, Name, Description)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Tag ..................The alarm tag to be matched. Specify an empty string (" ") to match all alarm
tags.

Name ............... The alarm name to be matched. Specify an empty string (" ") to match all alarm
names.
 AlarmNextTagRec 181

Description ......The alarm description to be matched. Specify an empty string (" ") to match all
alarm descriptions.

Return Value The alarm record identifier or -1 if no match is found.

Related Functions AlarmFirstTagRec, AlarmGetFieldRec, AlarmAckRec, AlarmDisableRec, AlarmEnableRec,
AlarmGetDsp, AlarmGetThresholdRec, AlarmSetThresholdRec, MsgRPC
Examples See AlarmDisableRec.

AlarmSetInfo
Description Changes the display parameters for the alarm list displayed at a specified AN.
Syntax AlarmSetInfo(AN, Type, Value)

AN....................The AN where the alarm list originally commenced. (An alarm page can contain
more than one alarm list). You can also specify:

-1 .... Change the display parameters of all alarm lists displayed on the page.
0 ..... Change the display parameters of the alarm list where the cursor is
positioned.

Type .................The type of data:

0 ..... Alarm page number. The vertical offset (in pages) from the AN where the
alarm list commenced.
1 ..... Alarm list offset. The vertical offset (in lines) from the AN where the
alarm list commenced.
2 ..... Category of alarms displayed on the alarm list. To specify all categories
use a value of 0.
....... You can use a group handle to display a group of categories. (A group can
be defined using Groups - from the Project Editor System menu - or by
using the GrpOpen()function.) Before you can display a group of
categories, you must first open the group using the GrpOpen() function.
You would usually do this by entering the GrpOpen() function as the Page
entry command for your alarm page (set using Page Properties). Note,
however, that you should not close the group until you close the display
page. If you do, the group will be destroyed and the group handle will
become invalid. The page would then be unable to continue displaying the
desired group. You would normally close the group by entering the
GrpClose()function as the Page exit command.
182 AlarmSetInfo

3 ..... Type of alarms displayed on the alarm list. See AlarmDsp() for a list of
these types.
4 ..... Display all alarms according to the format and fonts specified for one
category (specified in Value).
5 ..... The display format for all alarms specified by a format handle. All the
alarm categories will display in the same format.
6 ..... The display font for all alarms specified by a font handle. All the alarms
will appear in the same font and colour.
7 ..... The priority of the alarms to be displayed in the alarm list. You can use a
group number to display a group of priorities.
....... You can use a group handle to display a group of priorities. (A group can
be defined using Groups - from the Project Editor System menu - or by
using the GrpOpen()function.) Before you can display a group of priorities,
you must first open the group using the GrpOpen() function. You would
usually do this by entering the GrpOpen() function as the Page entry
command for your alarm page (set using Page Properties). Note, however,
that you should not close the group until you close the display page. If you
do, the group will be destroyed and the group handle will become invalid.
The page would then be unable to continue displaying the desired group.
You would normally close the group by entering the GrpClose()function as
the Page exit command.
8 ..... Alarm list display mode.
Set Value to 0 (zero) to display by Category.
Set Value to 1 to display by Priority.

Value ...............The new value of the parameter.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen, AlarmDsp, AlarmGetInfo
Examples
/* In the following examples, the display parameters of the alarm list
where the cursor is positioned are changed. */
! Change the vertical offset (pages) to 2.
AlarmSetInfo(0,0,2);
! Change the vertical offset (lines) to 15.
AlarmSetInfo(0,1,15);
! Change the alarm category to 10.
AlarmSetInfo(0,2,10);
! Change the type of alarms displayed to type 5 (all hardware alarms).
AlarmSetInfo(0,3,5);

/* In the following examples, the display parameters of the alarm list

at AN 20 are changed. */
 AlarmSetInfo 183

! Display all alarms with category 120 format and fonts

AlarmSetInfo(20, 4, 120);
! Display all alarms with a new format
hFmt=FmtOpen("MyFormat","{Name}{Desc,20}",0);
AlarmSetInfo(20, 5, hFmt);
! Display all alarms with a new font
hFont = DspFont("Times",-60,black,grey);
AlarmSetInfo(20, 6, hFont);

/* The following example displays all alarms with categories 1-10, 20,
or 25. Before AlarmSetInfo() is run, the page entry command for the
alarm display page is configured as follows:
On page entry hGrp=GrpOpen("MyGrp",1);
command StrToGrp(hGrp,"1..10,20,25");

Note that hGrp is defined in the variables database. The page exit command for the
alarm display page is configured as follows:

On page exit GrpClose(hGrp)

command

*/
AlarmSetInfo(20, 2, hGrp);

AlarmSetQuery
Description Allows you to choose which alarms display on a page, by calling a user-defined query function
to filter the alarms on specific criteria. The query function is called for each alarm, and only
alarms matching the criteria are displayed on the page.
There are two steps involved in using a query to display alarms:
• Write the Cicode function that will be used as the query function.
• Specify the query function and its arguments in a call to AlarmSetQuery().

NOTE: You can also use AlarmSetQuery() to remove filtering from an alarm list. AlarmSetQuery( -1, "", "" )
stops the query function filtering the display of alarms.

Syntax AlarmSetQuery(AN, QueryFunction, sArgs)

AN....................The AN where the alarm list originally commenced. (An alarm page can contain
more than one alarm list). You can also specify:

-1 .... Change the display parameters of all alarm lists displayed on the page.
184 AlarmSetQuery

0 ..... Change the display parameters of the alarm list where the cursor is
positioned.

QueryFunction The name of the Cicode query function written by the user.

Once this function has been specified, it is called for each alarm, and determines
whether or not the alarm should be displayed.
The query function must return an INT with a value of either TRUE or FALSE.
If a value of TRUE is returned, the alarm will be displayed. If the query function
returns FALSE, the alarm will be ignored and not displayed.
The query function's first parameter must be an INT. This parameter is initialised
with the record ID of the current alarm, providing the query function with
information about the alarm.
The query function's second parameter must also be an INT. It represents the
instance or event of an alarm, and is used in filtering the alarms for display.

sArgs ...............A list of arguments to be passed to the Cicode query function. The arguments are
enclosed by " " and separated by commas. This parameter is optional. If the
query function does not require parameters other than the default INT parameter,
then the list of arguments may be left out as follows:

AlarmSetQuery(0, "AlarmQueryDate");
In this case, the default value of an empty string will be used for the third
parameter.
If the query function requires values to be passed in by the user, the following
rules apply to determine the types of arguments:

Digits are interpreted as INT

Digits with decimals are interpreted as REAL

Anything enclosed by ^" ^" is interpreted as a STRING
For example, to pass an INT of 23, a string of "23/12/1999", and a REAL value
of 23.45 to the query function MyQueryDate(), AlarmSetQuery() should be
invoked in the following way:

AlarmSetQuery(0, 1 ,"MyQueryDate", "23, ^"23/12/1999^",

23.45");
The query function MyQueryDate() would be defined as follows:

INT
 AlarmSetQuery 185

FUNCTION
MyQueryDate(INT nRID, INT nVer, INT iOne, STRING sOne, REAL
rOne)
.......
.......
END
The types of the arguments listed in AlarmSetQuery() should match the types of
the arguments defined in the query function.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmGetFieldRec, AlarmSetInfo

Example
!Sets MyQueryDate() as the query function and provides the arguments 23,
23/12/1999, and 23.45
AlarmSetQuery(0, "MyQueryDate", "23, ^"23/12/1999^", 23.45");

!Removes filtering by the current query function from all alarm lists on
the page
AlarmSetQuery(-1, "", "");

AlarmSetThreshold
Description Changes the thresholds (i.e. High High, Low etc.) of analog alarms. This function acts on the
analog alarm where the cursor is positioned. Use this function to change (at run time) the
threshold values that were specified in the Analog Alarms database. Threshold changes made
using this function are permanent (i.e. they are saved to the project). The display format
currently specified for the record (in the Analog Alarms form) will be applied to these values.
Syntax AlarmSetThreshold(Type, Value)

Type .................The type of threshold:

0 ..... High high

1 ..... High
2 ..... Low
3 ..... Low low
4 ..... Deadband
5 ..... Deviation
186 AlarmSetThreshold

6 ..... Rate of change

Value ...............The new value of the threshold. Enter a blank value "" to remove the threshold.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmSetThresholdRec
Examples

System Keyboard
Key Sequence SetHighHigh ### Enter

Command AlarmSetThreshold(0, Arg1)

Comment Change the threshold of a high high alarm

System Keyboard
Key Sequence SetHigh ### Enter

Command AlarmSetThreshold(1, Arg1)

Comment Change the threshold of a high alarm

System Keyboard
Key Sequence SetLow ### Enter

Command AlarmSetThreshold(2, Arg1)

Comment Change the threshold of a low alarm

 AlarmSetThreshold 187

System Keyboard
Key Sequence SetlowLow ### Enter

Command AlarmSetThreshold(3, Arg1)

Comment Change the threshold of a low low alarm

AlarmSetThresholdRec
Description Changes the threshold (i.e. High High, Low etc.) of analog alarms by the alarm record number.
You can call this function only on an Alarms Server for alarms on that server, or on the
redundant server (if a redundant server is configured). However, a client can call this function
remotely by using the MsgRPC() function.
Threshold changes made using this function are permanent (i.e. they are saved to the project).
The display format currently specified for the record (in the Analog Alarms form) will be applied
to these values.
Syntax AlarmSetThresholdRec(Record, Type, Value)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()or AlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()or AlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()orAlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

Type .................The type of threshold:

0 ..... High high

1 ..... High
2 ..... Low
3 ..... Low low
188 AlarmSetThresholdRec

4 ..... Deadband
5 ..... Deviation
6 ..... Rate of change

Value ...............The new value of the threshold. Enter a blank value "" to remove the threshold.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmSetThreshold, MsgRPC

AlarmSplit
Description Duplicates an entry (where the cursor is positioned) in the alarm summary display. You can use
this function to add another comment to an alarm summary entry. You would normally call this
function from a keyboard command.
Syntax AlarmSplit()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmSumSplit
Examples

System Keyboard
Key Sequence Split

Command AlarmSplit()

Comment Duplicates an alarm summary entry

AlarmSumAppend
Description Appends a new blank record to the alarm summary. Use this function to add new alarm
summary entries, either for actual alarms or as special user summary entries.
If you specify a valid alarm tag in the sTag field, the summary entry is linked to the actual alarm.
If you specify an asterisk '*' as the first letter of the tag, the summary entry becomes a user event.
User events are not attached to alarm records, so their status will never change. You must
manually change the status of the user event, by calling the AlarmSumSet() function with the
 AlarmSumAppend 189

index returned by AlarmSumAppend(). As user events are not attached to alarms, they don't
have the alarm fields - so the AlarmSumGet() function will not return any field data.
You can use user events to keep a record of logins, or control operations that you need to display
in the alarm summary etc. To set the {ONTIME} {OFFTIME} etc. data, use the AlarmSumSet()
function.
Syntax AlarmSumAppend(sTag)

sTag .................The alarm tag to append. Use an asterisk '*' as the first letter to append a user
event to the alarm summary. Note that if you using this 'user event mode' the
AlarmSumAppend function returns the alarm summary index - not the error
code.

Return Value The index of the alarm summary entry, or -1 if the record could not be appended.
Related Functions AlarmSumSet
Examples
! Append alarm to summary display
AlarmSumAppend("CV101");

! Append user event

iIndex = AlarmSumAppend("*MyEvent");
AlarmSumSet(iIndex, "Comment", "My event comment");
AlarmSumSet(iIndex, "OnTime", TimeCurrent());

AlarmSumCommit
Description Commits the alarm summary record to the alarm summary device. Alarm summaries are
normally written to the alarm summary device just before they are deleted from the summary
queue. The length of time that alarm summary entries remain in the alarm summary queue is
controlled by [Alarm]SummaryTimeout parameter
This function allows you to commit the alarm summary records now, rather than when they are
deleted from the queue.
Syntax AlarmSumCommit(Index)

Index ................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev, AlarmSumGet,
AlarmSumFind
190 AlarmSumCommit

Examples
/* This function commits all alarm summary entries that match the
specified tag. */
FUNCTION
SumCommitTag(STRING sTag)
INT Next;
INT Index;
STRING Name;

Index=AlarmSumFirst();
WHILE Index<>-1 DO
Name=AlarmSumGet(Index,"Tag");
Next=AlarmSumNext(Index);
IF Name=sTag THEN
AlarmSumCommit(Index);
END
Index=Next;
END
END

AlarmSumDelete
Description Deletes an alarm summary entry. You identify the alarm summary entry by the Index, returned
by one of the alarm summary search functions.
By embedding this function in a loop, you can delete a series of alarm summary entries. To start
deleting from the oldest entry, call the AlarmSumFirst() function to get the index, and then call
AlarmSumNext() in a loop. To delete back from the most recent entry, call AlarmSumLast() and
then AlarmSumPrev() in a loop.
You can also get the Index from the AlarmSumFind() function, which finds an alarm summary
entry by its alarm record identifier and time of activation.
You can call this function only on an Alarms Server and only for alarms on that server.
Syntax AlarmSumDelete(Index)

Index................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

Return Value 0 (zero) if the specified alarm entry exists, otherwise an error is returned.
Related Functions AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev, AlarmSumGet,
AlarmSumFind
 AlarmSumDelete 191

Examples
/* This function deletes all alarm summary entries that match the
specified tag. */
FUNCTION
SumDelTag(STRING sTag)
INT Next;
INT Index;
STRING Name;

Index=AlarmSumFirst();
WHILE Index<>-1 DO
Name=AlarmSumGet(Index,"Tag");
Next=AlarmSumNext(Index);
IF Name=sTag THEN
AlarmSumDelete(Index);
END
Index=Next;
END
END

AlarmSumFind
Description Finds the alarm summary index for an alarm that you specify by the alarm record identifier and
alarm activation time (OnTime). You can use this index in the AlarmSumGet() function to get
field data from an alarm record, in the AlarmSumSet() function to change the existing data in
that record, or in the AlarmSumDelete() function to delete the record.
To work with a series of alarm summary records, call this function to get the index, and then call
either AlarmSumNext() to move forwards in the summary, or AlarmSumPrev() to move
backwards in the summary.
You can call this function only on an Alarms Server. However, a client can call this function
remotely by using the MsgRPC() function.
Syntax AlarmSumFind(Record, OnTime)

Record .............The alarm record number, returned from any of the following alarm functions:

..... AlarmFirstCatRec()orAlarmNextCatRec()- used to search for a record by

alarm category, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstPriRec()orAlarmNextPriRec()- used to search for a record by
alarm priority, area, and type (acknowledged, disabled, etc.).

..... AlarmFirstTagRec()or
AlarmNextTagRec()- used to search for a record by
alarm tag, name, and description.
192 AlarmSumFind

..... AlarmGetDsp()- used to find the record that is displayed at a specified AN,
for either an alarm list or alarm summary entry. Set the sField argument in
AlarmGetDsp() to "RecNo".
To store this value, use data type Int in Cicode or Long for variable tags (Long
needs 4 bytes).

OnTime............ The ON time of the alarm associated with the Record, that is, the time that the
alarm was activated.

Return Value The index of the alarm summary entry, or -1 if no alarm summary entry is found.
Related Functions AlarmSumGet, AlarmSumSet, AlarmSumDelete, AlarmSumFirst, AlarmSumNext,
AlarmSumLast, AlarmSumPrev, MsgRPC
Examples
/* This function sets the summary comment from the alarm record number
and the ontime of the summary event. */
FUNCTION
SumSetComment(INT An, STRING sComment)
INT nRecord;
INT iOnTime;

INT Index;

iOnTime=StrToTime(AlarmGetDsp(An,"OnTime"))+TimeMidNight(TimeCurrent()
);
nrecord=StrToInt(AlarmGetDsp(An,"RecNo"));

Index = AlarmSumFind(nRecord, iOnTime);

IF Index<>-1 THEN
AlarmSumSet(Index,"Comment", sComment);
END
END

AlarmSumFirst
Description Gets the index of the oldest alarm summary entry. You can use this index in the AlarmSumGet()
function to get field data from an alarm record, in the AlarmSumSet() function to change the
existing data in that record, or in the AlarmSumDelete() function to delete the record.
To work with a series of alarm summary records, call this function to get the index, and then call
AlarmSumNext() within a loop, to move forwards in the alarm summary.
You can call this function only on an Alarms Server.
Syntax AlarmSumFirst()

Return Value The index of the oldest alarm summary entry, or -1 if no alarm summary entry is found.
 AlarmSumFirst 193

Related Functions AlarmSumGet, AlarmSumSet, AlarmSumDelete, AlarmSumNext, AlarmSumLast,

AlarmSumPrev
Examples
/* This function finds all alarm summary entries that match the
specified tag and sets the "OffTime" to the time specified. The alarm
entry is not acknowledged or set to the off state, the alarm summary
"OffTime" field is all that is affected. */
FUNCTION
SumSetTime(STRING sTag, INT Time)
INT Index;
STRING Name;

Index=AlarmSumFirst();
WHILE Index<>-1 DO
Name=AlarmSumGet(Index,"Tag");
IF Name=sTag THEN
AlarmSumSet(Index,"OffTime",Time);
END
Index=AlarmSumNext(Index);
END
END

AlarmSumGet
Description Gets field data from an alarm summary entry. The data is returned as a string. You identify the
alarm summary entry by the Index, returned by one of the alarm summary search functions.
By embedding this function in a loop, you can get data from a series of alarm summary entries.
To start from the oldest entry, call the AlarmSumFirst() function to get the index, and then call
AlarmSumNext() in a loop. To work back from the most recent entry, call AlarmSumLast() and
then AlarmSumPrev() in a loop.
You can also get the Index from the AlarmSumFind() function, which finds an alarm summary
entry by its alarm record identifier and time of activation.
You can call this function only on an Alarms Server. However, a client can call this function
remotely by using the MsgRPC() function.
Syntax AlarmSumGet(Index, sField)

Index ................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

sField ...............The name of the field from which to extract the data:

Tag ............ Alarm tag

194 AlarmSumGet

AckDate .....Alarm acknowledged date

AckTime ....Alarm acknowledged time
Category.....Alarm category
Comment ...Alarm comment
DeltaTime ..Alarm active time
Desc ...........Alarm description
Help ......... Help page
Name..........Alarm name
OffDate ......Alarm OFF date
OffTime .....Alarm OFF time
OnDate.......Alarm ON date
OnTime ......Alarm ON time
State ...........Alarm state

Return Value Field data from the alarm summary entry (as a string).
Related Functions AlarmSumSet, AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev,
AlarmSumFind, MsgRPC
Examples See AlarmSumFirst.

AlarmSumLast
Description Gets the index of the most recent alarm summary entry. You can use this index in the
AlarmSumGet() function to get field data from an alarm record, in the AlarmSumSet() function
to change the existing data in that record, or in the AlarmSumDelete() function to delete the
record.
To work with a series of alarm summary records, call this function to get the index, and then call
AlarmSumPrev() within a loop, to move backwards in the alarm summary.
You can call this function only on an Alarms Server.
Syntax AlarmSumLast()

Return Value The index of the most recent alarm summary entry, or -1 if no alarm summary entry is found.
Related Functions AlarmSumGet, AlarmSumSet, AlarmSumDelete, AlarmSumPrev, AlarmSumFirst,
AlarmSumNext
 AlarmSumLast 195

Examples
/* This function finds all alarm summary entries that match the
specified tag and
sets the "OffTime" to the time specified. The alarm entry is not
acknowledged or set
to the off state, the alarm summary "OffTime" field is all that is
affected. */
FUNCTION
SumSetTime(STRING sTag, INT Time)
INT Index;
STRING Name;

Index=AlarmSumLast();
WHILE Index<>-1 DO
Name=AlarmSumGet(Index,"Tag");
IF Name=sTag THEN
AlarmSumSet(Index,"OffTime",Time);
END
Index=AlarmSumPrev(Index);
END
END

AlarmSumNext
Description Gets the index of the next alarm summary entry, that is, the entry that occurred later than the
entry specified by Index. You can use this index in the AlarmSumGet() function to get field data
from an alarm record, in the AlarmSumSet() function to change the existing data in that record,
or in the AlarmSumDelete() function to delete the record.
You can use this function to work with a series of alarm summary records. Call the
AlarmSumFirst() or AlarmSumFind() function to get the index, and then call AlarmSumNext()
within a loop, to move forwards in the alarm summary.
You can also get the index of an entry as soon as it displays on the alarm summary. Alarm
summary entries are recorded with the most recent entry at the end of the list. Call
AlarmSumLast() to get the index for the most recent entry, and then call AlarmSumNext() to get
the index for the next entry that occurs.
You can call this function only on an Alarms Server.
Syntax AlarmSumNext(Index)

Index ................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

Return Value The index of the next alarm summary entry or -1 if no more alarm summary entries are found.
196 AlarmSumNext

Related Functions AlarmSumGet, AlarmSumSet, AlarmSumDelete, AlarmSumFirst, AlarmSumLast,

AlarmSumPrev, AlarmSumFind
Examples See AlarmSumFirst.

AlarmSumPrev
Description Gets the index of the previous alarm summary entry, that is, the entry that occurred before the
entry specified by Index. You can use this index in the AlarmSumGet() function to get field data
from an alarm record, in the AlarmSumSet() function to change the existing data in that record,
or in the AlarmSumDelete() function to delete the record.
You can use this function to work with a series of alarm summary records. Call the
AlarmSumLast() or AlarmSumFind() function to get the index, and then call AlarmSumPrev()
within a loop, to move backwards in the alarm summary.
You can call this function only on an Alarms Server.
Syntax AlarmSumPrev(Index)

Index................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

Return Value 0 (zero) if the alarm summary entry exists, otherwise an error is returned.
Related Functions AlarmSumGet, AlarmSumSet, AlarmSumDelete, AlarmSumFirst, AlarmSumNext,
AlarmSumLast, AlarmSumFind
Examples See AlarmSumLast.

AlarmSumSet
Description Sets field information in an alarm summary entry. You identify the alarm summary entry by the
Index, returned by one of the alarm summary search functions.
By embedding this function in a loop, you can change field data in a series of alarm summary
entries. To start from the oldest entry, call the AlarmSumFirst() function to get the index, and
then call AlarmSumNext() in a loop. To work back from the most recent entry, call
AlarmSumLast() and then AlarmSumPrev() in a loop.
You can also get the Index from the AlarmSumFind() function, which finds an alarm summary
entry by its alarm record identifier and time of activation.
You can call this function only on an Alarms Server.
Syntax AlarmSumSet(Index, sField, sData)
 AlarmSumSet 197

Index ................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

sField ...............The name of the field in which data is to be set:

AckTime ... Alarm acknowledged time

Comment... Alarm comment
OffMilli ..... Alarm millisecond off time
OffTime..... Alarm OFF time
OnMilli...... Alarm millisecond on time
OnTime ..... Alarm ON time
State........... Alarm state

sData ...............The new value of the field.

Return Value 0 (zero) if the alarm summary entry exists, otherwise an error is returned.
Related Functions AlarmSumGet, AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev,
AlarmSumFind
Examples See AlarmSumFirst.

AlarmSumSplit
Description Duplicates the alarm summary entry identified by Index. You can use this function to add
another comment to an alarm summary entry.
You can call this function only on an Alarms Server and only for alarms on that server. To
duplicate an alarm summary entry on a Display Client, use the AlarmSplit() function - the entry
at the cursor position is duplicated.
Syntax AlarmSumSplit(Index)

Index ................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

Return Value 0 (zero) if the alarm summary entry exists, otherwise an error is returned.
Related Functions AlarmSumGet, AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev,
AlarmSumFind, AlarmSplit
198 AlarmSumSplit

Examples
/* This function finds the first alarm summary entry that matches the
specified tag, splits
that entry and then adds the specified comment to the new entry. */
FUNCTION
AlarmSplitAdd(STRING Tag, STRING Comment)
INT Index;
STRING Name;

Index=AlarmSumFirst();
WHILE Index<>-1 DO
Name=AlarmSumGet(Index,"Tag");
IF Name=sTag THEN
AlarmSumSplit(Index);
Index=AlarmSumFirst();
AlarmSumSet(Index,"Comment",Comment);
Index=-1;
ELSE
Index=AlarmSumNext(Index);
END
END
END

AlarmSumType
Description Retrieves a value that indicates a specified alarm’s type, ie. whether it’s a digital alarm, an
analog alarm, hardware alarm, etc.
Syntax AlarmSumType(Index)

Index................The alarm summary index (returned from the AlarmSumFirst(),

AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or
AlarmSumFind() function).

Return Value A number that represents one of the following alarm types:
0 = digital alarm
1 = analogue alarm
2 = advanced alarm
3 = Argyle digital alarm
4 = Argyle analogue alarm
5 = user generated event
6 = high resolution alarm
 AlarmSumType 199

7 = hardware alarm

-1 indicates an invalid response to the request.

Related Functions AlarmSumGet, AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev,
AlarmSumFind, AlarmSplit

AnByName
Description Retrieves the animation point number of an ActiveX object.
Syntax AnByName(sName)

sName ..............The name for the object in the form of "AN" followed by its AN number, eg.
"AN35". This name is used to access the object.

Return Value The animation point number of the object - if successful, otherwise an error is returned.
Related Functions CreateControlObject()

ArcCos
Description Calculates the arccosine of an angle.
Syntax ArcCos(Number)

Number ............The cosine of the angle.

Return Value The arccosine (the angle, in radians) of Number.

Related Functions Cos
Examples
Variable=ArcCos(0.4);
! Sets Variable to 1.1592...

ArcSin
Description Calculates the arcsine of an angle.
Syntax ArcSin(Number)
200 ArcSin

Number............ The sine of the angle.

Return Value The arcsine (the angle, in radians) of Number.

Related Functions Sin
Examples
Variable=ArcSin(1);
! Sets Variable to 1.5707...

ArcTan
Description Calculates the arctangent of an angle.
Syntax ArcTan(Number)

Number............ The tangent of the angle.

Return Value The arctangent (the angle, in radians) of Number.

Related Functions Tan
Examples
Variable=ArcTan(0.4);
! Sets Variable to 0.3805...

AreaCheck
Description Determines whether the current user has access to a specified area.
Syntax AreaCheck(Area)

Area.................The area number (0 - 255)

Return Value TRUE (1) if the user has access to the Area or FALSE (0) if not.
Related Functions GetArea, GetPriv
Examples
IsArea = AreaCheck(5);
 Ass 201

Ass
Description Associates a variable tag with a Super Genie. This association is only made for the next Super
Genie you display (either in the current window or in a new window). You cannot create an
association for a Super Genie that is already displayed. You must call this function once for
every Super Genie substitution string in the Super Genie.
This function provides the lowest level of support for associating Super Genie variables with
physical tags. The higher level functions (listed below) are simpler to use.
Syntax Ass(hWin, nArg, sTag, nMode)

hWin ................The association will be created for the next Super Genie to display in the
window specified here - enter the window number or:

-3 .... for the current window.

-2 .... for the next new window displayed.

nArg.................The argument number (substitution string number) of the Super Genie string to
be replaced by sTag. For example, to replace ?INT 3? with sTag, set nArg to 3.

sTag .................The variable tag that will replace the Super Genie substitution string. The tag
must be the same data type as that specified by the Super Genie substitution
string. For example, only a digital tag could replace the substitution string
?DIGITAL 4?. If the substitution string does not specify a type (eg. ?5?), you
can use any type except STRING.

nMode..............The mode of the association. Set to 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples
// Associate variable tag PV123 with the next Genie to display in the
current window
Ass(-3, 5, "PV123", 0);

AssChain
Description Chains the associations from the current Super Genie to a new Super Genie. Use this function to
display a new Super Genie when you already have one displayed. The new Super Genie will
inherit all the associations of the first Super Genie.
202 AssChain

This function provides the lowest level of support for chaining associations from one Super
Genie to another. You should call the higher level functions AssChainPage(), AssChainWin(),
and AssChainPopUp() - these functions are simpler to use.
Syntax AssChain(hDest, hSource, nMode)

hDest ............... The next Super Genie to display in the window specified here will inherit all the
associations of the current Super Genie - enter the window number, or:

-3.... for the current window

-2.... for the next new window displayed.

hSource ...........The number of the window containing the source Super Genie (i.e. the Super
Genie from which the associations will be inherited).

nMode .............The mode of the association. Set to 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples
// Copy all associations from the current Super Genie to !NewGenie
AssChain(WinNumber(), WinNumber(), 0);
PageDisplay("!NewGenie");

AssChainPage
Description Chains the associations from the current Super Genie to a new Super Genie, and displays the
new Super Genie (in the current window). Use this function to display a new Super Genie when
you already have one displayed. The new Super Genie will inherit all the associations of the first
Super Genie.
Syntax AssChainPage(sPage)

sPage...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainWin, AssChainWinFree,
AssChainPopUp
Examples
// Display new Super Genie in current window, using current associations
 AssChainPage 203

AssChainPage("!NewGenie");

AssChainPopUp
Description Chains the associations from the current Super Genie to a new Super Genie, and displays the
new Super Genie in a new popup window. Use this function to display a new Super Genie in a
new popup window when a Super Genie is already displayed. The new Super Genie will inherit
all the associations of the first.
NOTE: This function prevents the Super Genie from being opened more than once (at the same
time). However, the same Super Genie with different associations can be opened.
Syntax AssChainPopUp(sPage)

sPage ...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree
Examples
// Display new Super Genie in new popup using current associations
AssChainPopUp("!NewGenie");

AssChainWin
Description Chains the associations from the current Super Genie to a new Super Genie, and displays the
new Super Genie in a new window. The new window will be of the same type as the current
window. Use this function to display a new Super Genie in a new window when a Super Genie
is already displayed. The new Super Genie will inherit all the associations of the first.
Syntax AssChainWin(sPage, X, Y, Mode)

sPage ...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.

X ......................The x pixel coordinate of the top left corner of the window.

Y.......................The y pixel coordinate of the top left corner of the window.

Mode................The mode of the window:

204 AssChainWin

0 ..... Normal page.

1 ..... Page child window. The window is closed when a new page is displayed,
e.g. when the PageDisplay() or PageGoto() function is called. The parent is
the current active window.
2 ..... Window child window. The window is closed automatically when the
parent window is freed with the WinFree() function. The parent is the
current active window.
4 ..... No re-size. The window is displayed with thin borders and no
maximise/minimise icons. The window cannot be re-sized.
8 ..... No icons. The window is displayed with thin borders and no
maximise/minimise or system menu icons. The window cannot be re-sized.
16 .. No caption. The window is displayed with thin borders, no caption, and no
maximise/minimise or system menu icons. The window cannot be re-sized.
32 .. Echo enabled. When enabled, all keyboard echo, prompts, and error
messages are displayed on the parent window. This mode should only be
used with child windows (e.g. Mode 1 and 2).
64 .. Always on top.
128 ........... Open a unique window. This mode prevents this window from
being opened more then once.
256 .............Display the entire window. This mode ensures that no parts of the
window will appear off the screen
512 .............Open a unique Super Genie. This mode prevents a Super Genie
from being opened more than once (at the same time). However, the
same Super Genie with different associations can be opened.
1024 ...........Disables dynamic resizing of the new window, overriding the setting
of the [Page]DynamicSizing parameter.
You can select multiple modes by adding modes together (for example, set Mode
to 9 to open a page child window without maximise, minimise, or system menu
icons).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainWinFree, AssChainPage,
AssChainPopUp
Examples
// Displays a new super genie in a new window using the current
associations
AssChainWin("!NewGenie", 100, 200, 1 + 8);
 AssChainWinFree 205

AssChainWinFree
Description Saves the first 8 tag associations on an existing Super Genie, closes it, then assigns the 8 tags to a
new window. This allows a Super Genie popup window to call another popup window, and
close the parent popup.
This function is effectively the same as the AssChainWin() function, but frees the current Super
Genie.
Syntax AssChainWinFree(sPage, X, Y, Mode)

sPage ...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.

X ......................The x pixel coordinate of the top left corner of the window.

Y.......................The y pixel coordinate of the top left corner of the window.

Mode................The mode of the window:

0 ..... Normal page.

1 ..... Page child window. The window is closed when a new page is displayed,
e.g. when the PageDisplay() or PageGoto() function is called. The parent is
the current active window.
2 ..... Window child window. The window is closed automatically when the
parent window is freed with the WinFree() function. The parent is the
current active window.
4 ..... No re-size. The window is displayed with thin borders and no
maximise/minimise icons. The window cannot be re-sized.
8 ..... No icons. The window is displayed with thin borders and no
maximise/minimise or system menu icons. The window cannot be re-sized.
16... No caption. The window is displayed with thin borders, no caption, and no
maximise/minimise or system menu icons. The window cannot be re-sized.
32... Echo enabled. When enabled, all keyboard echo, prompts, and error
messages are displayed on the parent window. This mode should only be
used with child windows (e.g. Mode 1 and 2).
64... Always on top.
128 ........... Open a unique window. This mode prevents this window from
being opened more then once.
256............. Display the entire window. This mode ensures that no parts of the
window will appear off the screen
206 AssChainWinFree

512 .............Open a unique Super Genie. This mode prevents a Super Genie
from being opened more than once (at the same time). However, the
same Super Genie with different associations can be opened.
1024 ...........Disables dynamic resizing of the new window, overriding the setting
of the [Page]DynamicSizing parameter.
You can select multiple modes by adding modes together (for example, set Mode
to 9 to open a page child window without maximise, minimise, or system menu
icons).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainWin, AssChainPage,
AssChainPopUp
Examples
// Close the current genie window and display a new genie using the
current associations
AssChainWinFree("!GeniePopup", 200, 300, 1 + 8);

Assert
Description Verifies that the specified expression is TRUE. If then expression is FALSE, the current task
will be halted. This is useful for ensuring that sensitive code is not executed in the event of an
error.
This function can be used in a debug mode, where the failed assertion will be logged to the
Kernel and SysLog.DAT, with the time, date, Cicode file name, and line number. Additionally
the operator will be prompted with a dialog. The debug mode can be set by using the
[Code]DebugMessage parameter or DebugMsgSet() function.
NOTE: If you have the Citect will start debugger on hardware errors option set in the Cicode
Editor, the Debugger will start with the position before the Halt() instruction. You must 'step
over' this command if you want to continue debugging the function that called the Assert().
Syntax Assert(bCondition)

bCondition.......The boolean expression. This expression must evaluate to TRUE (1) or FALSE
(0).

Return Value None. However, if the assertion fails (the condition is FALSE), error 347 is generated.
Related Functions Halt, DebugMsg, DebugMsgSet, CodeTrace, TraceMsg, ErrLog
Examples
INT
FUNCTION
 Assert 207

FileDisplayEx(STRING sFileName);
INT hFile;

hFile = FileOpen(sFileName, "r");

Assert(hFile <> -1);
.
.
.
FileClose(hFile);
RETURN 0;
END

AssInfo
Description Gets association information about the current Super Genie (i.e. information about a variable tag
that has been substituted into the Super Genie). You can only call this function on a Super Genie
after all the associations are completed.
Use this function to display association information as part of the Super Genie. For example, if
you have a Super Genie that is a loop controller, you could display the name of the loop at the
top of the loop controller box. Each time the Super Genie is used with different associations
(specifically a different tag name association) the correct loop name will be displayed.
Syntax AssInfo(nArg, nType)

nArg.................When you associate variable tags with super Genies, the Super Genie
substitution strings are replaced by variable tags. The nArg argument allows you
to get information about one of those variable tags. All you need to know is
which substitution string it replaced when the association was performed.

Enter the argument number (substitution string number) of the relevant

substitution string. For example, if you want information about the variable that
replaced substitution string...
....... ?INT 3?
...then set nArg to 3.

nType ...............The type of information to get:

0 ..... Tag name of the association

1 ..... Engineering units
2: .... Raw zero scale
3 ..... Raw full scale
4 ..... Engineering zero scale
208 AssInfo

5 ..... Engineering full scale

6 ..... Width of the format
7 ..... Number of decimal places of format.

Return Value The value of the information as a string.

Related Functions AssTag, AssPage, AssWin, AssPopUp, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp, AssScaleStr
Examples
sTag = AssInfo(1, 0); // Get the name of association 1
sEngLow = AssInfo(1, 4); // get the low engineering scale of
association 1

AssPage
Description Associates up to eight variable tags with a Super Genie and displays the Super Genie in the
current window. The first variable tag (sTag1) replaces Super Genie substitution string 1. The
second variable tag (sTag2) replaces substitution string 2, and so on.
This function has the same effect as calling Ass() or AssTag() eight times, and then calling the
PageDisplay() function. The AssPage() function provides a quick way of associating eight Super
Genie variables and displaying the Super Genie - at the same time.
If you want to associate more than eight tags with the Super Genie, you must call the
AssVarTags(), AssTag(), or Ass() function to create the associations before you call this
function.
Syntax AssPage(sPage, sTag1..8)

sPage...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.
 AssPage 209

sTag1..8 ...........The first eight physical tags to be associated with the Super Genie. For any
given Super Genie, the variable tags will replace the Super Genie substitution
strings as follows:
Variable tag... replaces substitution string...
sTag1 1
sTag2 2
sTag3 3
sTag4 4
sTag5 5
sTag6 6
sTag7 7
sTag8 8

Because there is a strict correlation between the variable tag numbers and the
substitution string numbers, it is important to know how your Super Genie
substitutions are numbered. For example, if your Super Genie has three unique
substitution strings, numbered 1, 3, & 4, you must enter a blank ("") for sTag2.
The variable tags that you specify here must be the same data type as that
specified by the relevant Super Genie substitution strings. For example, only a
digital tag could replace the substitution string ?DIGITAL 4?. If the
substitution string does not specify a type (eg. ?5?), you can use any type except
STRING.
Return Value 0 (zero) if successful, otherwise an error is returned.
Related Functions AssTag, AssWin, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples
// Associate 3 tags with the Super Genie then display the Super Genie
AssPage("!MyGenie", "PV123", "OP123", "SP123");

AssPopUp
Description Associates up to eight variable tags with a Super Genie and displays the Super Genie in a popup
window. The first variable tag (sTag1) replaces Super Genie substitution string 1. The second
variable tag (sTag2) replaces substitution string 2, and so on.
This function has the same effect as calling the Ass() function or the AssTag() function eight
times, and then calling the WinNewAt() function to create a window at the position of the
210 AssPopUp

mouse. The AssPopUp() function is a quick way of associating eight Super Genie variables and
displaying the Super Genie in a new window - at the same time.
If you want to associate more than eight tags with the Super Genie, you must call the
AssVarTags(), AssTag(), or Ass() function to create the associations before you call this
function.
NOTE: This function prevents the Super Genie from being opened more than once (at the same
time). However, the same Super Genie with different associations can be opened.
Syntax AssPopUp(sPage, sTag1..8)

sPage...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.

sTag1..8........... The first eight physical tags to be associated with the Super Genie. For any
given Super Genie, the variable tags will replace the Super Genie substitution
strings as follows:
Variable tag... replaces substitution string...
sTag1 1
sTag2 2
sTag3 3
sTag4 4
sTag5 5
sTag6 6
sTag7 7
sTag8 8

Because there is a strict correlation between the variable tag numbers and the
substitution string numbers, it is important to know how your Super Genie
substitutions are numbered. For example, if your Super Genie has three unique
substitution strings, numbered 1, 3, & 4, you must enter a blank ("") for sTag2.
The variable tags that you specify here must be the same data type as that
specified by the relevant Super Genie substitution strings. For example, only a
digital tag could replace the substitution string ?DIGITAL 4?. If the
substitution string does not specify a type (eg. ?5?), you can use any type except
STRING.
Return Value 0 (zero) if successful, otherwise an error is returned.
Related Functions AssTag, AssPage, AssWin, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
 AssPopUp 211

Examples
// Associate 3 tags with the Super Genie then display it
AssPopUp("!MyGenie", "PV123", "OP123", "SP123");

AssScaleStr
Description Gets scale information about the associations of the current Super Genie (i.e. scale information
about a variable tag that has been substituted into the Super Genie). You can only call this
function on a Super Genie after all the associations are completed.
Use this function to display association scale information as part of the Super Genie. For
example, if you have a bar graph illustrating output, you could indicate zero, 50%, and full scale
output on the vertical axis of the graph. Each time the Super Genie is used with different
associations the correct scale values will be displayed.
The value is returned as a formatted string using the association format specification and
(optionally) the engineering units.
Syntax AssScaleStr(nArg, Percent, EngUnits)

nArg.................When you associate variable tags with super Genies, the Super Genie
substitution strings are replaced by variable tags. The nArg argument allows you
to get scale information about a particular variable tag. All you need to know is
which substitution string the tag replaced when the association was performed.

Enter the argument number (substitution string number) of the relevant

substitution string. For example, if you want scale information about the
variable that replaced substitution string...
....... ?INT 3?
...then set nArg to 3.

Percent ............The percentage of full scale of the returned value.

EngUnits..........Determines if the value is returned with engineering units:

0 ..... Do not return the value with engineering units

1 ..... Return the value with engineering units

Return Value The scale of the association (as a string).

Related Functions AssInfo, TagScaleStr
Examples
// Display the zero, 50% and full scale of the variable that was
substituted for Super Genie arg no. 3
212 AssScaleStr

DspText(31,0,AssScaleStr(3, 0, 1));
DspText(32,0,AssScaleStr(3, 50, 1));
DspText(33,0,AssScaleStr(3, 100, 1));

AssTag
Description Associates a variable tag with the a Super Genie. The association will only be created for the
next Super Genie you display in the current window, and will only come into effect after you re-
display the Super Genie. You must call this function once for every substitution string in the
current Super Genie. You cannot use this function to create associations for variables that will
display in new windows.
Syntax AssTag(nArg, sTag)

nArg.................The argument number (substitution string number) of the Super Genie string to
be replaced by sTag. For example, to replace ?INT 3? with sTag, set nArg to 3.

sTag.................The variable tag that will replace the Super Genie substitution string. The tag
must be the same data type as that specified by the Super Genie substitution
string. For example, only a digital tag could replace the substitution string
?DIGITAL 4?. If the substitution string does not specify a type (eg. ?5?), you
can use any type except STRING.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples
// Associate variable tag PV123 and PV124 with !MyGenie
AssTag(1, "PV123");
AssTag(2, "PV124");
// Re-display the current Super Genie
PageDisplay("!MyGenie");

AssTitle
Description Sets the runtime window title to the tag name of the first variable substituted into the Super
Genie.
Syntax AssTitle(Mask, Prefix, Suffix)

Mask................The number of characters to mask (hide) from the right of the title string
(optional).
 AssTitle 213

Prefix ...............A string to add to the beginning of the title string (optional).

Suffix................A string to add to the end of the title string (optional).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples

AssVarTags
Description Associates up to eight variable tags with a Super Genie. This association is only made for the
next Super Genie you display (either in the current window or in a new window). This function
has an offset that allows you to specify which substitution string the first variable tag will
replace. This means that if you have a Super Genie with more than 8 substitution strings, you
can use this function repeatedly (while increasing the offset), until you have associated all the
necessary variable tags.
This function has the same effect as calling the Ass() function or the AssTag() function eight
times. The AssVarTags() function is a quick way of associating up to eight Super Genie
variables at the same time.
Syntax AssVarTags(hWin, nOffset, sTag1..8)

hWin ................The association will be created for the next Super Genie to display in the
window specified here - enter the window number or:

-3 .... for the current window.

-2 .... for the next new window displayed.

nOffset .............By default, the first variable tag (sTag1) will replace substitution string 1, and
sTag2 will replace substitution string 2, and so on. Enter an offset to change this
so that sTag1 replaces a substitution string other than the first. For example, an
offset of 8 means that sTag1 replaces string 9 instead of the default string 1
(8+1=9), and sTag2 replaces string 10 instead of string 2 (8+2=10) etc. This
214 AssVarTags

means that you can use this function repeatedly to associate more than eight
variables.

sTag1..8........... The physical variable tags (up to eight) to be associated with the Super Genie.
For any given Super Genie, the variable tags will replace the Super Genie
substitution strings as follows:
If nOffset is 0... sTag1 will replace the substitution string 1,
sTag2 will replace the substitution string 2, etc.
If nOffset is 8... sTag1 will replace the substitution string 9,
sTag2 will replace the substitution string 10, etc.

Because there is a strict correlation between the variable tag numbers and the
substitution string numbers, it is important to know how your Super Genie
substitutions are numbered. For example, if your Super Genie has three unique
substitution strings, numbered 1, 3, & 4, you must enter a blank ("") for sTag2.
Return Value No value is returned.
Related Functions AssTag, AssPage, AssWin, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples
// Associate 12 variables to the Super Genie
AssVarTags(WinNumber(), 0, "PV123", "SP123", "OP123", "PV124", "SP124",
"OP124", "PV125", "SP125");
AssVarTags(WinNumber(), 8, "OP125", "PV126", "SP126", "OP126");
PageDisplay("!MyGenie"); // Display the Super Genie

AssWin
Description Associates up to eight variable tags with a Super Genie, and displays the Super Genie in a new
window. This function has the same effect as calling the Ass() or AssTag() function eight times,
and then calling the WinNewAt() function. The AssWin() function is a quick way of associating
eight Super Genie variables and creating a new window - at the same time.
If you want to associate more than eight tags with the Super Genie you must call the
AssVarTags(), AssTag(), or Ass() function to create the associations before you call this
function.
Syntax AssWin(sPage, X, Y, Mode, sTag1..8)

sPage...............The page name of the Super Genie. If you prefixed your Super Genie page name
with an exclamation mark (!), remember to include it here.

X ......................The x pixel coordinate of the top left corner of the window.

 AssWin 215

Y.......................The y pixel coordinate of the top left corner of the window.

Mode................The mode of the window:

0 ..... Normal page.

1 ..... Page child window. The window is closed when a new page is displayed,
e.g. when the PageDisplay() or PageGoto() function is called. The parent is
the current active window.
2 ..... Window child window. The window is closed automatically when the
parent window is freed with the WinFree() function. The parent is the
current active window.
4 ..... No re-size. The window is displayed with thin borders and no
maximise/minimise icons. The window cannot be re-sized.
8 ..... No icons. The window is displayed with thin borders and no
maximise/minimise or system menu icons. The window cannot be re-sized.
16... No caption. The window is displayed with thin borders, no caption, and no
maximise/minimise or system menu icons. The window cannot be re-sized.
32... Echo enabled. When enabled, all keyboard echo, prompts, and error
messages are displayed on the parent window. This mode should only be
used with child windows (e.g. Mode 1 and 2).
64... Always on top.
128 ........... Open a unique window. This mode prevents this window from
being opened more then once.
256............. Display the entire window. This mode ensures that no parts of the
window will appear off the screen
512............. Open a unique Super Genie. This mode prevents a Super Genie
from being opened more than once (at the same time). However, the
same Super Genie with different associations can be opened.
1024........... Disables dynamic resizing of the new window, overriding the setting
of the [Page]DynamicSizing parameter.
You can select multiple modes by adding modes together (for example, set Mode
to 9 to open a page child window without maximise, minimise, or system menu
icons).

sTag1..8 ...........The first eight physical tags to be associated with the Super Genie. For any
given Super Genie, the variable tags will replace the Super Genie substitution
strings as follows:
Variable tag... replaces substitution string...
sTag1 1
216 AssWin

sTag2 2
sTag3 3
sTag4 4
sTag5 5
sTag6 6
sTag7 7
sTag8 8

Because there is a strict correlation between the variable tag numbers and the
substitution string numbers, it is important to know how your Super Genie
substitutions are numbered. For example, if your Super Genie has three unique
substitution strings, numbered 1, 3, & 4, you must enter a blank ("") for sTag2.
The variable tags that you specify here must be the same data type as that
specified by the relevant Super Genie substitution strings. For example, only a
digital tag could replace the substitution string ?DIGITAL 4?. If the
substitution string does not specify a type (eg. ?5?), you can use any type except
STRING.
Return Value 0 (zero) if successful, otherwise an error is returned.
Related Functions AssTag, AssPage, AssPopUp, AssInfo, AssChain, AssChainPage, AssChainWin,
AssChainWinFree, AssChainPopUp
Examples
// Associate 3 tags with the Super Genie
// then display the new window at (100,200) in mode 9
AssWin("!MyGenie", 100, 200, 1 + 8, "PV123", "OP123", "SP123");

Beep
Description Beeps the internal speaker or sound card (installed in the computer). If you use the internal
speaker on your computer, the function does not return until the sound has completed. If you use
a sound card, the function returns immediately and the sound plays in the background.
Use the Windows Control Panel to set up waveforms.
Syntax Beep(nSound)

nSound.............The type of sound:

-1 ... Standard beep

0 .... Default beep waveform
 Beep 217

1 .... Critical stop waveform

2 .... Question waveform
3 .... Exclamation waveform
4 .... Asterisk waveform

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspPlaySound
Examples
/* Beeps the speaker with the default waveform. */
Beep(0);

CallEvent
Description Calls the event function and runs it in a window. If no event is configured, no function is called.
Use this function to add a user event, or to simulate a call to an event function.
Syntax CallEvent(Window, Type)

Window............The number of the window, returned from the WinNew(), WinNewAt(), or

WinNumber() function.

Type .................The type of event:

0 .... The mouse has moved. When the mouse moves the callback function is
called. The return value must be 0.
1 .... A key has been pressed. When the user presses a key, the callback function
is called after Citect checks for hot keys. If the return value is 0, Citect
checks for key sequences. If the return value is not 0, Citect assumes that
you will process the key and does not check the key sequence. It is up to
you to remove the key from the key command line.

NOTE:....... If you are using a right mouse button click as an event, you should
read about the ButtonOnlyLeftClick parameter.
2 .... Error event. This event is called if an error occurs in Cicode, so you can
write a single error function to check for your errors. If the return value is
0, Citect continues to process the error and generates a hardware error - it
may then halt the Cicode task. If the return value is not 0, Citect assumes
that you will process the error, and continues the Cicode without generating
a hardware error.
218 CallEvent

3 ..... Page user communication error. A communication error has occurred in

the data required for this page. If the return value is 0 (zero), Citect still
animates the page. If the return value is not zero, Citect does not update the
page.
4 ..... Page user open. A new page is being opened. This event allows you to
define a single function that is called when all pages are opened. The return
value must be 0.
5 ..... Page user close. The current page is being closed. This event allows you to
define a single function that is called when all pages are closed. The return
value must be 0.
6 ..... Page user always. The page is active. This event allows you to define a
single function that is called when all pages are active. The return value
must be 0.
7 ..... Page communication error. A communication error has occurred in the
data required for this page. Reserved for use by Citect.
8 ..... Page open. This event is called each time a page is opened. Reserved for
use by Citect.
9 ..... Page close. This event is called each time a page is closed. Reserved for
use by Citect.
10 ... Page always. This event is called while a page is active. Reserved for use
by Citect.
11..17 Undefined.
18 ... Report start. The report server is about to start a new report. This event is
called on the report server. The return value must be 0.
19 ... Device history. A device history has just completed. The return value must
be 0.
20 ... Login. A user has just logged in.
21 ... Logout. A user has just logged out.
22 ... Trend needs repainting. This event is called each time Citect re-animates a
real-time trend or scrolls an historical trend. You should use this event to
add additional animation to a trend, because Citect deletes all existing
animation when a trend is re-drawn. (For example, if you want to display
extra markers, you must use this event.)
23 ... Hardware error occurred.
24 ... Keyboard cursor moved. This event is called each time the keyboard
command cursor moves. The cursor can be moved by the cursor keys, the
mouse, or the Cicode function KeySetCursor(). Note that you can find
 CallEvent 219

where the keyboard command cursor is located by calling the function

KeyGetCursor().
25.... Network shutdown. A Shutdown network command has been issued.
26.... Runtime system shutdown and restart. (Required because of configuration
changes.)
27.... Event. An event has occurred.
28.... Accumulator. An accumulator has logged a value.
29.... Slider. A slider has been selected.
30.... Slider. A slider has moved.
31.... Slider. A slider has been released (i.e. stopped moving).

NOTE:....... 1) While responding to slider events 29, 30, and 31, you can set any
variables but you cannot call functions that cause immediate changes
to animations on the page (e.g. DspText() and DspSym()).
2) Types 29, 30, & 31 relate only to V3.xx and V4.xx animations,
and will be superseded in future releases.
32.... Shutdown. Citect is being shutdown.
33... 127 Reserved for future Citect use.
128... 256... User defined events. These events are for your own use.

Return Value 0 (zero) if successful, otherwise an error is set. To view the error, use the IsError() function.
Related Functions OnEvent, GetEvent, WinNew, WinNewAt, WinNumber, IsError
Examples
! Call Event Type 1 - key has been pressed in the current window.
Number=WinNumber();
CallEvent(Number,1);

ChainEvent
Description Calls an event function using the function handle. This creates a chain of event handlers from a
single event. Use the GetEvent() function to get the function number of the current event
handler.
Syntax ChainEvent(hFn)

hFn ..................The function handle, as returned from the GetEvent() function.

Return Value The return value of the called event function.

220 ChainEvent

Related Functions OnEvent, GetEvent

Examples See GetEvent.

CharToStr
Description Converts an ASCII code into a string.
Syntax CharToStr(ASCIICode)

ASCIICode ......The ASCII code to convert.

Return Value A string containing the converted ASCII code.

Related Functions StrSetChar
Examples
str = CharToStr(65);
! Sets str to "A".

CitectColourToPackedRGB
Description Converts a Citect colour into a packed RGB colour value that can be understood by an ActiveX
object.
Syntax CitectColourToPackedRGB(nCitectColour)

nCitectColour..The Citect colour (as defined in the labels database) to be converted into a
packed RGB colour.

Return Value The packed RGB colour value - if successful, otherwise an error is returned.
Related Functions PackedRGBToCitectColour

CitectInfo
Description Gets information about a Citect variable. This function returns internal statistics and other
information about the Citect runtime system.
Syntax CitectInfo(sGroup, sName, sType)

sGroup.............The name of the group to which the variable belongs. Valid group names are:
"General", "Port", "IODevice", "Network", "Stats", "Memory", or "Disk".
 CitectInfo 221

sName ..............The name of the variable. This name depends on sGroup:

"General" The name is ignored.

"Port" The name of the I/O port configured in the database (with the Ports
database). The port information is only valid for an I/O server. If the port
name is "total", the total statistics for the I/O server are returned.
"IODevice" The name of the I/O Device configured in the I/O Devices
database.
"Network" The name is ignored.
"Stats" The name of the statistics buffer or Statistical Information Record (SIR):
"Digital Alm" Digital Alarms
"Analog Alm" Analog Alarms
"Advance Alm" Advanced Alarms
"High Res. Al" High Resolution Alarms
"Citect n" The Citect window where n is the window number (returned from
the WinNumber() function)
"Code n" The user Cicode task (thread) where n is the task handle (returned
from the TaskHnd() function)
"Reset" Reset the Citect statistics.
"Memory" The name is ignored.
"Disk" The disk drive to access:
0 = the current drive
1 = A:
2 = B:
3 = C: etc.

sType................The type of information to get, depending on sGroup:

"General" General statistics:

0 ..... CPU usage
1 ..... Citect kernel cycles per second
2 ..... Citect kernel tasks per second
3 ..... Citect Kernel boot time
4 ..... Citect Kernel running time (in seconds)
5 ..... Citect startup time
222 CitectInfo

6 ..... Citect running time in seconds

7 ..... The CPU Index. (This is a rough guide of the CPU performance. On a
Compaq 486/25 it will return 25.)
8 ..... Total read requests
9 ..... Total Read requests per second
10 ... Total write requests
11 ... Total write requests per second
12 ... Total Physical read requests
13 ... Total Physical read requests per second
14 ... Total Physical write requests
15 ... Total Physical write requests per second
16 ... Total Blocked read requests
17 ... Total Blocked write requests
18 ... Total Digital read requests
19 ... Total Register read requests
20 ... Total Digital read requests per second
21 ... Total Register read requests per second
22 ... Total Cache reads count
23 ... Total Cache reads %
24 ... Overall Average response time (ms)
25 ... Overall Minimum response time (ms)
26 ... Overall Maximum response time (ms)
27 ... Request sample for response times
28 ... Static point count limit
29 ... Dynamic point count limit
"Port" Port information for the I/O Server:
0 ..... Read requests
1 ..... Write requests
2 ..... Physical read requests
3 ..... Physical write requests
4 ..... Cached read requests
 CitectInfo 223

5 ..... Cached write requests

6 ..... Blocked read requests
7 ..... Blocked write requests
8 ..... Read requests per second
9 ..... Write requests per second
10.... Error count
11.... Read bytes counter
12.... Channel usage %
13.... Read bytes per second
14.... Statistics, minimum read time
15.... Statistics, maximum read time
16.... Statistics, average read time
17.... Statistics, time of samples
18.... Statistics, number of samples
"IODevice" I/O Device information for the I/O Device:
0 ..... Client side status: 1 = running, 16 = offline
1 ..... I/O Server state: 1 = running, 2 = standby running, 16 = offline
2 ..... If this I/O Device is a standby device
3 ..... Last generic error
4 ..... Last driver error
5 ..... Error count
6 ..... Initialization count
7 ..... Statistics, minimum read time
8 ..... Statistics, maximum read time
9 ..... Statistics, average read time
10.... Statistics, number of samples
"Network " Network statistical information:
0 ..... Read Network Control Blocks (NCBs)
1 ..... Maximum pending read NCBs
2 ..... Minimum pending read NCBs
224 CitectInfo

3 ..... Current pending read NCBs

4 ..... Number of short read NCBs
5 ..... Write NCBs
6 ..... Maximum pending write NCBs
7 ..... Minimum pending write NCBs
8 ..... Current pending write NCBs
9 ..... Number of short write NCBs
10 ... Total NCBs
11 ... Maximum pending total NCBs
12 ... Minimum pending total NCBs
13 ... Current pending total NCBs
14 ... Number of short total NCBs
15 ... Minimum send response time
16 ... Maximum send response time
17 ... Average send response time
18 ... Send packet count
"Stats" Statistical information:
0 ..... Minimum time between code executions (cycles)
1 ..... Maximum time between code executions (cycles)
2 ..... Average time between code executions (cycles)
3 ..... Total cycle time
4 ..... Minimum time to execute the code
5 ..... Maximum time to execute the code
6 ..... Average time to execute the code
7 ..... Total execute time
"Memory" Memory information:
0 ..... Free virtual memory
1 ..... Free windows system resources as %
2 ..... Free Physical Memory
3 ..... Memory Paging File Size
 CitectInfo 225

"Disk" Disk information:

0 ..... Free disk space
1 ..... Total disk space

Return Value The type of information (as an integer).

Related Functions IODeviceInfo, WinNumber, TaskHnd
Examples
! Get free memory
FreeMemory = CitectInfo("Memory", "", 0);

! Get free disk space on C:

FreeDisk = CitectInfo("Disk", 3, 0);

! Get max cycle time for digital alarms

MaxCycleTime = CitectInfo("Stats","Digital Alm","1");

ClipCopy
Description Copies a string to the Windows clipboard. When the string is in the clipboard, you can paste it to
any Windows program.
Syntax ClipCopy(sText)

sText ................The string to copy to the clipboard.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ClipWriteLn
Examples
ClipCopy("put this in clipboard");

ClipPaste
Description Pastes a string from the Windows clipboard.
Syntax ClipPaste()

Return Value The contents of the clipboard (as a string). If the clipboard is empty, an empty string is returned.
Related Functions ClipReadLn
226 ClipPaste

Examples
/* Get string from clipboard into sText. */
sText = ClipPaste();

ClipReadLn
Description Reads a single line of text from the Windows clipboard. With this function, you can read a block
of text from the clipboard - line by line. Call the function once to read each line of text from the
clipboard. When the end of the clipboard is reached, an empty string is returned.
Syntax ClipReadLn()

Return Value One line of text from the clipboard (as a string). If the clipboard is empty, an empty string is
returned.
Related Functions ClipPaste
Examples
/* Get first line of text from clipboard. */
sText = ClipReadLn();
WHILE StrLength(sText) > 0 DO
! Do something with text
...
! Read next line of clipboard
sText = ClipReadLn();
END

ClipSetMode
Description Sets the format of data sent to the Windows clipboard.
Syntax ClipSetMode(nMode)

nMode .............The mode of the data:

1 ..... ASCII Text

2 ..... CSV (Comma separated values) format
You can select multiple modes by adding modes together.

Return Value The value of the previous mode.

Related Functions ClipCopy, ClipWriteLn
 ClipSetMode 227

Examples
/* Set the clipboard to CSV mode, write two values, and reset the
clipboard to the original mode. */
nOldMode = ClipSetMode(2);
ClipCopy("100,200");
ClipSetMode(nOldMode);

ClipWriteLn
Description Writes a line of text to the Windows clipboard. With this function, you can write any amount of
text to the clipboard. Call this function once for each line of text. To terminate the block of text,
call this function and pass an empty string.
Syntax ClipWriteLn(sText)

sText ................The line of text to write to the clipboard, or an empty string ("") to end the write
operation.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ClipCopy
Examples
ClipWriteLn("first line of text");
ClipWriteLn("second line of text");
ClipWriteLn(""); ! End of write operation

ClusterGetName
Description Returns the names of the primary and standby cluster servers to which Citect is currently
connected (sPrimary and sStandby, as set using the ClusterSetName function).
Syntax ClusterGetName(sPrimary, sStandby, nMode)

sPrimary ..........The variable containing the name of the cluster’s primary server (i.e. that which
was set as sPrimary using the ClusterSetName() function).

sStandby ..........The variable containing the name of the cluster’s standby server (i.e. that which
was set as sStandby using the ClusterSetName() function).

nMode..............The mode is for future expansion of the function - set to 0 (zero).

Return Value The status of the get name.

228 ClusterGetName

Related Functions ClusterSetName,

Examples
// Return and display the server names.//
ClusterGetName(sPrimary, sStandby, 0);
Prompt("Name of Cluster" + sPrimary);

ClusterSetName
Description Connects to a specific cluster server (Reports Server, Alarms Server etc.). Citect will disconnect
from the current cluster before connecting to the server you specify here.
This function would be used for switching the information displayed on the Global Client. For
example, if your system consists of plants A, B, and C, you could include this function in a
button command to connect to the Reports Server for Plant B. Once connected, you could then
display any information from that server.
Syntax ClusterSetName(sPrimary, sStandby, nMode)

sPrimary..........The name of the cluster’s primary server (Reports Server, Alarms Server etc.), as
defined using the Computer Setup Wizard. When the ClusterSetName()
function is used, Citect will attempt to connect to this server.

sStandby ..........The name of the cluster’s standby server (Reports Server, Alarms Server etc.), as
defined using the Computer Setup Wizard. If the sPrimary server is unavailable
when the ClusterSetName() function is used, Citect will attempt to connect to
this server.

If there is no standby server, enter an empty string for sStandby.

nMode .............The mode of the connection:

0 ..... If you select this mode, Citect will renew the last connection. If it was
connected to the sPrimary server, when this function was last used, it will
attempt to connect to it again. If it was last connected to the sStandby
server, it will attempt to connect to it again.
....... This mode is useful when a server is known to be unavailable, as it
facilitates faster cluster switching.
1 ..... Citect always attempts to connect to the sPrimary server first, each time
this function is used. If the sPrimary server is unavailable, Citect will try
the sStandby server.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ClusterGetName,
 ClusterSetName 229

Examples
// Connect to Cluster A, with server CITECTA1 as primary server, and
CITECTA2 as standby.//
ClusterSetName("CITECTA1", "CITECTA2", 0);
// Display the menu page for Cluster A Project.//
PageDisplay("MenuA");

CodeSetMode
Description Sets various execution modes for Cicode tasks in the current thread. Using this function, you
can specify whether to:

Write to a local image of an I/O Device.

Check if a variable is within range before writing it to the I/O Device.

Echo error messages to the operator.

Check the case of string data in Cicode.

Automatically call ReRead() to ensure the return of fresh PLC data.
Syntax CodeSetMode(Type, Value)

Type .................Type of mode:

0 .... Write to a local image of an I/O Device. If you set Value to 1, this mode is
enabled, and Cicode writes its local memory image of the I/O Device
whenever you write to the I/O Device. (Cicode assumes that most writes to
the I/O Device will be done immediately).
....... This local image might produce problems, or you might want to verify that
the data was actually written to the I/O Device. If you set Value to 0
(zero), this check is disabled, and Cicode does not write to the local
memory image.
1 .... Check if a variable is within range before writing it to the I/O Device. If
you set Value to 1, this mode is enabled. When a variable tag is modified,
Cicode checks the new value of the variable against the Scales specified in
the Variable Tags database. If the value of the variable is out of scale,
Cicode generates a hardware error, and does not write to the I/O Device.
....... If you set Value to 0 (zero), this check is disabled. Cicode writes the
variable to the I/O Device without checking if its value is within range.
2 .... Echo error messages to the operator. If you set Value to 1, this mode is
enabled. When a simple user error occurs (e.g. if the PageDisplay()
function is passed a bad page name), Cicode displays an error message at
the Error AN, and returns an error code from the function.
230 CodeSetMode

....... If you set Value to 0 (zero), the echo is disabled. Cicode does not display
the error message, and the output of the DspError() function is stopped.
3 .... Ignore the case of string data in the current thread of Cicode. If you set
Value to 1, this mode is enabled, and Citect will ignore case in string data.
For example, Citect will equate "Hello" to "HELLO".
....... If you set Value to 0 (zero), Citect will be case sensitive to string data. Case
sensitivity is used when a string comparison operation is performed. For
example:
... IF sStr1 = sStr2 THEN
....... (You can also make Citect case sensitive to strings in all of your Cicode,
using the [Code]IgnoreCase parameter.)
4 .... Automatically call the ReRead()function, at periods defined by the
[Code]TimeData parameter. If you set Value to 1, this mode is enabled.
This means that Cicode loops that continually request PLC data can be
provided with the most up to data values at all times. Similarly, you no
longer need to manually call ReRead() after long Cicode sleep periods.
(You can also specify that ReRead() is called automatically for all Cicode,
using the [Code]AutoReRead parameter.)
....... If you set Value to 0 (zero), Citect will not automatically call the ReRead()
function. You would select this option when you would rather call the
ReRead() function manually. For example, automatically updated PLC
data could cause problems for long running reports (reports that execute for
longer than the [Code]TimeData period). Instead of having the ReRead
function called automatically, you could call it manually at the completion
of the report.

Value ...............The value of the mode:

0 ..... Disable
1 ..... Enable

Return Value -1 if there is an error, otherwise the last value of the mode.
Examples
! disable local image write
CodeSetMode(0, 0);
 CodeTrace 231

CodeTrace
Description Traces Cicode into the Kernel and the SYSLOG.DAT file. Use this function for finding bugs in
your Cicode. It will trace all functions called, the arguments to those functions, and their return
values. It will also trace any errors, writes to the I/O Devices, and task state changes.
WARNING: You should only use this function during system development, because the
function can cause excessive loading on the CPU.
Syntax CodeTrace(hTask, nMode)

hTask ...............The Cicode task handle as returned from TaskHnd() function or any of the
following special values:

0 ..... Foreground Cicode.

-2 .... The next created task.
-3 .... All new created tasks.
-4 .... All tasks.

nMode..............The mode of the trace:

0 ..... Tracing off

1 ..... Trace user Cicode functions calls
2 ..... Trace in-built function calls
4 ..... Trace errors
8 ..... Trace writes to the I/O Devices
16.... Trace task state changes
-1 .... All modes (except 0)

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Assert, TaskHnd, DebugMsg, DebugMsgSet, TraceMsg, ErrLog
Examples
// Start tracing errors
CodeTrace(TaskHnd(), 4);
....
// Stop tracing
CodeTrace(TaskHnd(), 0);

// trace all functions in new task

CodeTrace(-2, 1 + 2);
TaskNew("MyFunc", "data", 0);
232 ComClose

ComClose
Description Closes a communication port. Any Cicode tasks that are waiting for a read or write operation to
complete (or that are retrying to read or write) return with a range error.
Citect automatically closes all communication ports at shutdown.
This function can only be called from an I/O Server.
Syntax ComClose(hPort)

hPort ...............The communication port handle, returned from the ComOpen() function. This
handle identifies the table where all data on the associated communication port is
stored.

Return Value 0 if the port is successfully closed, or an error if the port is already closed or if the port number is
invalid.
Related Functions ComOpen, ComRead, ComWrite
Examples See ComOpen.

ComOpen
Description Opens a communication port for access. The board and port must both be defined in the
database (using the Boards and Ports forms from the Communication menu).
If you try to open the same COM port twice with ComOpen(), the second open will fail and
return -1. Do not open COM ports twice, and always check the return value from ComOpen().
The communication system should be used for low speed communications only. You should not
use the communication functions to communicate with high speed PLCs - the performance may
not be adequate. If you need high speed communication (for communicating with PLCs, etc.),
you should write a protocol driver. Refer to the Citect "Driver Development Kit".
This function can only be called from an I/O Server.
Syntax ComOpen(sPort, iMode)

sPort................The port name as specified in the Ports database.

iMode ..............The mode of the open:

0 ..... Take control of the port from Citect. In this mode, you have complete
access to the port - Citect cannot use the port.
1 ..... Share the port with Citect. In this mode, you can write to the port, and
Citect can also use it.
 ComOpen 233

Return Value A communication port handle if the communication system is opened successfully, otherwise -1
is returned. The handle identifies the table where all data on the associated port is stored. You
can use the handle in the other communication functions, to send and receive characters from the
port.
Related Functions ComClose, ComRead, ComWrite
Examples
INT
FUNCTION
StartSerial(STRING sPort)
INT hPort;
hPort = ComOpen(sPort, 0);
IF hPort < 0 THEN
Prompt("Cannot open port " + sPort);
RETURN -1;
END
TaskNew("SerialRead", hPort, 0);
TaskNew("SerialWrite", hPort, 0);
ComClose(hPort);
RETURN 0;
END
INT
FUNCTION
SerialWrite(INT hPort)
STRING buffer;
INT error;
INT length;

WHILE 1 DO
! put data into buffer and set length
.
.
error = ComWrite(hPort, buffer, length, 2);
IF error THEN
Prompt("Error Writing port");
ComReset(hPort);
END
END

RETURN 0;
END

INT
FUNCTION
SerialRead(INT hPort)
STRING buffer;
INT length;
INT total;
INT error;
234 ComOpen

total = 0;

WHILE 1 DO
length = 128; ! must set length as read modifies
error = ComRead(hPort, buffer, length, 2);
IF error THEN
Prompt("Error from port " + error : ####);
ComReset(hPort);
ELSE
! get data from buffer, length is set to number read
.
.
END
END

RETURN 0;
END

ComRead
Description Reads characters from a communication port. The characters are read from the communication
port into a string buffer. If no characters have arrived after the specified timeout, the function
returns with a timeout error. If the timeout is 0, the function gets any characters that have
arrived from the last call, and returns immediately.
You use the iLength variable to specify the length of the buffer, or the maximum number of
characters to read when ComRead() is called. When ComRead() returns, iLength is set to the
actual number of characters read. Because iLength is modified by this function, you must reset it
before each call.
You should not treat the string buffer as a normal string - it has no string terminator. Use the
StrGetChar() function to extract characters from the buffer.
Do not call ComRead() while another ComRead() is still pending on the same port, because it
can produce unexpected results.
This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
This function can only be called from an I/O Server.
Syntax ComRead(hPort, sBuffer, iLength, iTimeOut)

hPort ...............The communication port handle, returned from the ComOpen() function. This
handle identifies the table where all data on the associated communication port is
stored.

sBuffer .............The buffer into which to put the characters. The actual number of characters
read is returned in iLength.
 ComRead 235

iLength.............The number of characters to read into the buffer. The maximum length you may
read in one call is 128 characters. When the function returns, this variable is set
to the actual number of characters read.

iTimeOut..........The timeout for the read to complete.

If iTimeOut = 0 (zero), the function checks for characters in the buffer and
returns.
If iTimeOut > 0, the function returns after this number of seconds - if no
characters have been received.
If iTimeOut < 0, the function waits forever for characters.

Return Value 0 (zero) if the read is successful, otherwise an error is returned.

Related Functions ComOpen, ComClose, ComWrite, StrGetChar
Examples See ComOpen.

ComReset
Description Resets the communication port.
This function can only be called from an I/O Server.
Syntax ComReset(hPort)

hPort................The communication port handle, returned from the ComOpen() function. This
handle identifies the table where all data on the associated communication port is
stored.

Return Value 0 (zero) if the write is successful, otherwise an error is returned.

Related Functions ComOpen, ComClose, ComRead, StrSetChar
Examples See ComOpen.

ComWrite
Description Writes characters to a communication port. The characters are written from the string buffer to
the port. If the characters have not been transmitted after the specified timeout, the function
returns with a timeout error. If the timeout is 0, the function returns immediately and the
characters are transmitted in the background.
236 ComWrite

ComWrite() does not treat the buffer as a true string, but rather as an array of characters of the
length specified - you can send any character to the communication port. Use the StrSetChar()
function to build the buffer.
Do not call ComWrite() while another ComWrite() is still pending on the same port, because it
can produce unexpected results.
You use the iLength variable to specify the length of the buffer, or the maximum number of
characters to write when ComWrite() is called. When ComWrite() returns, iLength is reset to
zero.
This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
This function can only be called from an I/O Server.
Syntax ComWrite(hPort, sBuffer, iLength, iTimeOut)

hPort ...............The communication port handle, returned from the ComOpen() function. This
handle identifies the table where all data on the associated communication port is
stored.

sBuffer .............The buffer from which to write the characters.

iLength ............The number of characters to write from the buffer. The maximum number of
characters you can write is 128.

iTimeOut .........The timeout for the write to complete.

If iTimeOut = 0 (zero), the characters are copied to the communication buffer

and the function returns immediately - the characters are transmitted in the
background.
If iTimeOut > 0, the function returns after this number of seconds - if the
characters cannot be transmitted.
If iTimeOut < 0, the function waits forever to transmit the characters.

Return Value 0 (zero) if the write is successful, otherwise an error is returned.

Related Functions ComOpen, ComClose, ComRead, StrSetChar
Examples See ComOpen.
 Cos 237

Cos
Description Calculates the trigonometric cosine of an angle.
Syntax Cos(Angle)

Angle................Any angle (in radians).

Return Value The cosine of Angle.

Related Functions ArcCos
Examples
Variable=Cos(0.7854);
! Sets Variable to 0.7071...

CreateControlObject
Description Creates a new instance of an ActiveX object.
An object created using this function remains in existence until the page is closed or the
associated Cicode Object is deleted. This function does not require an existing animation point.
When the object is created, an animation point is created internally. This animation point is
freed when the object is destroyed.
Syntax CreateControlObject(sClass, sName, x1, y1, x2, y2, sEventClass)

sClass ..............The class of the object. You can use the object’s human readable name, its
program ID, or its GUID. If the class does not exist, the function will fail.

For example:

"Calendar Control 8.0" - human readable name

"MSCAL.Calendar.7" - Program ID

"{8E27C92B-1264-101C-8A2F-040224009C02}" - GUID

sName ..............The name for the object in the form of "AN" followed by its AN number, eg.
"AN35". This name is used to access the object.

x1 .....................The x coordinate of the object’s top left hand corner as it will appear in your
Citect window.

y1 .....................The y coordinate of the object’s top left hand corner as it will appear in your
Citect window.
238 CreateControlObject

x2..................... The x coordinate of the object’s bottom right hand corner as it will appear in
your Citect window.

y2..................... The y coordinate of the object’s bottom right hand corner as it will appear in
your Citect window.

sEventClass ..... The string you would like to use as the event class for the object.

Return Value The newly created object, if successful, otherwise an error is generated.
Related Functions DspAnCreateControlObject(),CreateObject(),AnByName()
Examples

// This function creates a single instance of the calendar control at

the designated location with an object name of "CalendarEvent" and an
event class of "CalendarEvent"//
FUNCTION
CreateCalendar()
OBJECT Calendar;
STRING sCalendarClass;
STRING sEventClass;
STRING sObjectName;

sCalendarClass = "MSCal.Calendar.7";
sEventClass = "CalendarEvent";
sObjectName = "MyCalendar";
Calendar = CreateControlObject(sCalendarClass, sObjectName, 16, 100,
300, 340, sEventClass);
END

// This function shows how to change the title font of the calendar//
FUNCTION
CalendarSetFont(STRING sFont)
OBJECT Font;
OBJECT Calendar;

Calendar = ObjectByName("MyCalendar");
Font = _ObjectGetProperty(Calendar, "TitleFont");
_ObjectSetProperty(Font, "Name", sFont);
END

// This function shows how to change the background colour of the

calendar//
FUNCTION
CalendarSetColour(INT nRed, INT nGreen, INT nBlue)
OBJECT Calendar;

Calendar = ObjectByName("MyCalendar");
_ObjectSetProperty(Calendar, "BackColor",
PackedRGB(nRed,nGreen,nBlue));
 CreateControlObject 239

END

// This function shows how to call the NextDay method of the calendar//
FUNCTION
CalendarNextDay()
OBJECT Calendar;

Calendar = ObjectByName("MyCalendar");
_ObjectCallMethod(Calendar, "NextDay");
END

// This function shows you how to write a mouse click event handler for
the calendar//
FUNCTION
CalendarEvent_Click(OBJECT This)
INT nDay;
INT nMonth;
INT nYear;

nDay = _ObjectGetProperty(This, "Day");

nMonth = _ObjectGetProperty(This, "Month");
nYear = _ObjectGetProperty(This, "Year");
.
.
.
Your code goes here...
.
.
.
END

CreateObject
Description Creates a new instance of an ActiveX object. If you use this function to create an ActiveX
object, it will have no visual component (only the automation component will be created).
An object created with this function remains in existence until the variable it is assigned to goes
out of scope or the variable is set to NullObject.
Syntax CreateObject(sClass)

sClass ..............The class of the object. You can use the object’s human readable name, its
program ID, or its GUID. If the class does not exist, the function will fail.

For example:

"Calendar Control 8.0" - human readable name

"MSCAL.Calendar.7" - Program ID
240 CreateObject

"{8E27C92B-1264-101C-8A2F-040224009C02}" - GUID

Return Value The newly created object, if successful, otherwise an error is generated.
Related Functions DspAnCreateControlObject(),CreateControlObject()
Examples See CreateControlObject().

Date
Description Gets the current date in string format.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You should check that
the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax Date(Format)

Format.............The format required:

2 ..... Short date format, dd/mm/yy

3 ..... Long date format, day month year
9 ..... Extended date format, dd/mm/yyyy
If omitted, the default Format is 2.
All of these formats follow the Regional Settings found in the Windows Control
Panel.

Return Value The current date (in string format).

Related Functions Time, TimeToStr, TimeCurrent
Examples
/* If the current system date is 3rd November 1991 and the Windows date
format is dd/mm/yy; */
str = Date();
! Sets str to "3/11/91".
str = Date(2);
! Sets str to "3/11/91".
 Date 241

str = Date(3);
! Sets str to "3rd November 1991".

DateAdd
Description Adds time (in seconds) to a time/date value. The return value is in time/date variable format.
Use this function for time and date calculations.
Syntax DateAdd(Time, AddTime)

Time.................The time/date to which the AddTime will be added.

AddTime ..........The time to add, in seconds.

Return Value The date as a time/date variable.

Related Functions TimeToStr, DateSub
Examples
DateVariable=DateAdd(StrToDate("3/11/91"),86400);
! Adds 24 hours to 3/11/91.

NewDate=TimeToStr(DateVariable);
! Sets NewDate to 4/11/91.

DateDay
Description Gets the day of the month from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You should check that
the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax DateDay(Time)

Time.................The time/date variable.

Return Value The day of the month as an integer.

242 DateDay

Related Functions Date

Examples
! If the current system date is 3rd November 1991;
Variable=DateDay(TimeCurrent());
! Sets Variable to 3.

DateMonth
Description Gets the month from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You should check that
the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax DateMonth(Time)

Time................. The time/date variable.

Return Value The month of the year as an integer.

Related Functions Date
Examples
! If the current system date is 3rd November 1991;
Variable=DateMonth(TimeCurrent());
! Sets Variable to 11.

DateSub
Description Subtracts time (in seconds) from a time/date value. The return value is in time/date variable
format. Use this function for time and date calculations.
Syntax DateSub(Time, SubTime)

Time................. The time/date from which the SubTime will be subtracted.

SubTime...........The time to subtract, in seconds.

 DateSub 243

Return Value The time difference (in seconds) as an integer.

Related Functions Date, DateAdd
Examples
Variable=DateSub(StrToDate("05/11/91"),StrToDate("03/11/91"));
! Sets Variable to number of seconds between 2 date/times.

Str=TimeToStr(Variable,5);
! Sets Str to "48:00:00".

DateWeekDay
Description Gets the day of the week from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You should check that
the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax DateWeekDay(Time)

Time.................The time/date variable.

Return Value An integer representing the day of the week as follows:

1 Sunday
2 Monday
3 Tuesday
4 Wednesday
5 Thursday
6 Friday
7 Saturday
Related Functions Date, TimeCurrent
Examples
! If the current system date is Sunday, 3rd November 1991;
Variable=DateWeekDay(TimeCurrent());
244 DateWeekDay

! Sets Variable to 1.

DateYear
Description Gets the year from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You should check that
the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax DateYear(Time, Mode)

Time................. The time/date variable.

Mode ...............The format required:

0 ..... Short year, yy. If you use this mode during the year 2000, 0 (zero) will be
returned.
1 ..... Long year, yyyy
If omitted, the default Mode is 0.

NOTE: .......In the year 2000, 0 (zero) will be returned if mode 0 (zero) is used.

Return Value The year as an integer.

NOTE: In the year 2000, this function will return 0 (zero) if mode 0 (zero) is used.

Related Functions Date

Examples
! If the current system date is 3rd November 1991;
Variable=DateYear(TimeCurrent(),0);
! Sets Variable to 91.

! If the current system date is 18th October 2000;

Variable=DateYear(TimeCurrent(),0);
! Sets Variable to 0.

Variable=DateYear(TimeCurrent(),1);
! Sets Variable to 1991.
 DDEExec 245

DDEExec
Description Executes a command in an external Windows application. With this function, you can control
other applications that support DDE. Refer to the documentation provided with the external
Windows application to determine if DDE is supported and what functions can be called.
Other applications can execute any Cicode function (in-built or user-written) in Citect, by using
their own versions of the DDE execute command.
You cannot use DDEExec() to call macros on a remote computer or to call Access SQLs. For
these calls, Network DDE needs to pass the sDocument argument, so you must use the DDEh...
functions, passing sDocument in the DDEhInitiate() function.
Syntax DDEExec(sApplication, sCommand)

sApplication.....The application name (.EXE filename), e.g. "Excel".

sCommand .......The command that the application will execute.

Return Value 1 (one) if successful, otherwise an error is returned.

Related Functions DDEPost, DDERead, DDEWrite, DDEhExecute
Examples
/* Instruct the Excel application to recalculate its spreadsheet
immediately. */
DDEExec("Excel","[Calculate.Now()]");

DDEhExecute
Description Executes a command in an external Windows application. You must first start a conversation
with the DDEhInitiate function, and use the handle returned by that function to identify the
conversation.
With this function, you can control other applications that support DDE. Refer to the
documentation provided with your other Windows application to determine if DDE is supported
and what functions can be called.
Other applications can execute any Cicode function (in-built or user-written) in Citect, by using
their own versions of the DDE execute command.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax DDEhExecute(Handle, sCommand)

Handle .............The integer handle that identifies the DDE conversation, returned from the
DDEhInitiate function.
246 DDEhExecute

sCommand.......The command that the application will execute.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DDEhInititate, DDEhRequest, DDEhPoke, DDEhTerminate, DDEhGetLastError
Examples See DDEhInitiate.

DDEhGetLastError
Description Gets the latest error code issued from Windows for the conversation identified by the handle.
Syntax DDEhGetLastError(Handle)

Handle.............The integer handle that identifies the DDE conversation, returned from the
DDEhInitiate function.

Return Value The error code last issued from Windows DDEML (for that conversation):
DMLERR_ADVACKTIMEOUT 0x4000
DMLERR_BUSY 0x4001
DMLERR_DATAACKTIMEOUT 0x4002
DMLERR_DLL_NOT_INITIALIZED 0x4003
DMLERR_DLL_USAGE 0x4004
DMLERR_EXECACKTIMEOUT 0x4005
DMLERR_INVALIDPARAMETER 0x4006
DMLERR_LOW_MEMORY 0x4007
DMLERR_MEMORY_ERROR 0x4008
DMLERR_NOTPROCESSED 0x4009
DMLERR_NO_CONV_ESTABLISHED 0x400a
DMLERR_POKEACKTIMEOUT 0x400b
DMLERR_POSTMSG_FAILED 0x400c
DMLERR_REENTRANCY 0x400d
DMLERR_SERVER_DIED 0x400e
DMLERR_SYS_ERROR 0x400f
DMLERR_UNADVACKTIMEOUT 0x4010
DMLERR_UNFOUND_QUEUE_ID 0x4011
 DDEhGetLastError 247

Related Functions DDEhInititate, DDEhExecute, DDEhRequest, DDEhPoke, DDEhTerminate

Examples See DDEhInitiate.

DDEhInitiate
Description Starts a conversation with an external Windows application. When the data exchange is
complete, you should terminate the conversation to free system resources.
Syntax DDEhInitiate(sApplication, sDocument)

sApplication.....The application name (.EXE filename), e.g. "Excel".

sDocument .......The document, topic, or file name.

Return Value An integer handle for the conversation between Citect and the other application, or -1 if the
conversation is not started successfully. The handle is used by the other DDEh... functions, to
identify the conversation.
Related Functions DDEhExecute, DDEhRequest, DDEhPoke, DDEhTerminate, DDEhGetLastError
Examples
! Read from Excel spreadsheet
STRING
FUNCTION
GetExcelData();

INT hChannel;
STRING sData;
hChannel = DDEhInitiate("EXCEL", "DATA.XLS");
IF hChannel > -1 THEN
sData = DDEhRequest(hChannel, "R1C1");
DDEhTerminate(hChannel);
hChannel = -1;
END;
RETURN sData;
END

! Write to Excel spreadsheet

FUNCTION
SetExcelData(STRING sData);
INT hChannel;
hChannel = DDEhInitiate("EXCEL", "DATA.XLS");
IF hChannel > -1 THEN
DDEhPoke(hChannel, "R1C1", sData);
DDEhTerminate(hChannel);
hChannel = -1;
END;
248 DDEhInitiate

END

! Execute Excel Macro

FUNCTION
DoExcelMacro();
INT hChannel;
hChannel = DDEhInitiate("EXCEL", "DATA.XLS");
IF hChannel > -1 THEN
DDEhExecute(hChannel, "[RUN(^"TestMacro^")]");
DDEhTerminate(hChannel);
hChannel = -1;
END;
END

DDEhPoke
Description Writes a value to an external Windows application, e.g. an Excel spreadsheet. The value is
written once to the application. (To write the value dynamically, you must call this function at
the rate at which the data must be updated.)
You must first start a conversation with the DDEhInitiate function, and use the handle returned
by that function to identify the conversation.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax DDEhPoke(Handle, sItem, sValue)

Handle.............The integer handle that identifies the DDE conversation, returned from the
DDEhInitiate function.

sItem................A unique name for the item; for example, the variable name, field name, or
spreadsheet cell position.

sValue..............The value of the item.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DDEhInititate, DDEhExecute, DDEhRequest, DDEhTerminate, DDEhGetLastError
Examples See DDEhInitiate.
 DDEhRequest 249

DDEhRequest
Description Reads a value from an external Windows application, e.g. from an Excel spreadsheet. You must
first start a conversation with the DDEhInitiate function, and use the handle returned by that
function to identify the conversation.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax DDEhRequest(Handle, sItem)

Handle .............The integer handle that identifies the DDE conversation, returned from the
DDEhInitiate function.

sItem ................A unique name for the item; for example, the variable name, field name, or
spreadsheet cell position.

Return Value A string of data, or an empty string if the function fails.

Related Functions DDEhInititate, DDEhExecute, DDEhPoke, DDEhTerminate, DDEhGetLastError
Examples See DDEhInitiate.

DDEhTerminate
Description Closes the conversation identified by the handle, and frees the resources associated with that
conversation. After you call this function, the handle is no longer valid and must not be used.
With Network DDE, you might need to terminate and re-initiate a conversation. For example, if
you delete rows on an MS Access sheet, the deleted rows display as #DELETED until you
terminate and re-initiate the conversation.
Syntax DDEhTerminate(Handle)

Handle .............The integer handle that identifies the DDE conversation, returned from the
DDEhInitiate function.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DDEhInititate, DDEhExecute, DDEhRequest, DDEhPoke, DDEhGetLastError
Examples See DDEhInitiate.
250 DDEPost

DDEPost
Description Makes a Citect variable available for DDE linking (i.e. posts a value so that it can be used by
another application). The other application uses the item name (sItem) to access its value. (To
post the value dynamically, you must call this function at the rate at which the data must be
updated.)
After a value is posted, other Windows applications can read the value by using their own DDE
read functions. If the value of the posted variable changes, the other application(s) are informed
of the new value.
Syntax DDEPost(sItem, sValue)

sItem................A unique name for the item; for example, the variable name, field name, or
spreadsheet cell position.

sValue..............The value of the item.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DDEExec, DDERead, DDEWrite
Examples
/* To access the value in a cell in Excel, set the cell to
=Citect|Data!TAGONE
This will set the value of the Excel cell to 42. */

DDEPost("TAGONE",42);

DDERead
Description Reads values from an external Windows application, e.g. from an Excel spreadsheet.
NOTE: You can use the DDE client driver instead of this function. It is a simpler method of
reading I/O Device variables. Use this function when you want precise control over exactly
what you want from the DDE exchange.
Syntax DDERead(sApplication, sDocument, sItem, Mode)

sApplication ....The application name (.EXE filename), e.g. "Excel".

sDocument....... The document, topic, or file name.

sItem................A unique name for the item; for example, the variable name, field name, or
spreadsheet cell position.
 DDERead 251

Mode................A flag that tells the application whether or not to set up an advise loop:

0 ..... Do not set up advise loop.

1 ..... Set up advise loop (default).

Return Value The value (from the external application) as a string.

Related Functions DDEExec, DDEPost, DDEWrite
Examples
/* Read the value from R1C1 (Row1,Column1) of an Excel spreadsheet named
"Sheet1". */

DDERead("Excel","Sheet1","R1C1");

DDEWrite
Description Writes a value to an external Windows application, e.g. to an Excel spreadsheet. The value is
written once to the application. (To write the value dynamically, you must call this function at
the rate at which the data must be updated.)
In most cases, you would use the DDEPost() function and then use the DDE functions of the
target application to retrieve the data. Only use DDEWrite() if you cannot use the DDEPost()
function.
Syntax DDEWrite(sApplication, sDocument, sItem, sValue)

sApplication.....The application name (.EXE filename), e.g. "Excel".

sDocument .......The document, topic, or file name.

sItem ................A unique name for the item; for example, the variable name, field name, or
spreadsheet cell position.

sValue ..............The value of the item.

Return Value The value that is sent to the other application, or an empty string if the function fails.
Related Functions DDEExec, DDEPost, DDERead
Examples
/* Write the value of a Citect variable named TAGONE to R1C1
(Row1,Column1) of an Excel spreadsheet named "Sheet1". The value is in
string format. */

DDEWrite("Excel","Sheet1","R1C1",TAGONE);
252 DebugBreak

DebugBreak
Description Causes a breakpoint exception error to occur (error number 342). This allows programmers to
trap invalid states in their Cicode. If the Cicode Editor is not running, and the Citect will start
debugger on hardware errors option is set (Debug menu - Options), the Debugger will be
started. When the debugger starts, the correct Cicode file, function, and line will be displayed.
Syntax DebugBreak()

Return Value None.

Related Functions DspKernel, KerCmd, DumpKernel, TraceMsg.
Examples
!Check to see that rSpan is greater than zero else cause a break. If
rSpan equals 0 it would cause a Divide by Zero hardware error anyway.
IF rSpan > 0 THEN
rCalcRate = iAmount/rSpan;
ELSE
DebugBreak();
END

DebugMsg
Description Provides in-line debug messages of user Cicode, to the Kernel, Debugger Debug window, and
the SysLog.DAT file. This function can be enabled or disabled with the [Code]DebugMessage
parameter or DebugMsgSet() function at runtime.
Syntax DebugMsg(sMessage)

sMessage .........The debugging message to log. Be sure to enclose this message in double quotes
(" ").

Return Value None.

Related Functions Assert, DebugMsgSet, CodeTrace, TraceMsg, ErrLog
Examples
INT
FUNCTION
FileDisplayEx(STRING sFileName);
INT hFile;

hFile = FileOpen(sFileName, "r");

DebugMsg("When opening file " + sFileName + ", the handle was: " +
IntToStr(hFile));
.
 DebugMsg 253

.
.
FileClose(hFile);
RETURN 0;
END

DebugMsgSet
Description Enables/disables the DebugMsg() logging functionality. It also controls whether logging is
enabled for the Assert() function.
This function also sets the [Code]DebugMessage parameter appropriately.
Syntax DebugMsgSet(nMode)

nMode..............The logging mode:

0 ..... Disable logging.

1 ..... Enable logging.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Assert, DebugMsg
Examples

Buttons
Text Debug Enable

Command DebugMsgSet(1)

Comment Enable debug logging

DegToRad
Description Converts an angle from degrees to radians.
Syntax DegToRad(Angle)

Angle................Any angle (in degrees).

Return Value The angle in radians.

254 DegToRad

Related Functions RadToDeg

Examples
Variable=DegToRad(180);
! Sets Variable to 3.1415... (pi).

DevAppend
Description Appends a blank record to the end of a device. After the record is appended, you can use the
DevSetField() function to add data to fields in the record.
You must first call the DevOpen() function to get the device handle (hDev).
Syntax DevAppend(hDev)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 (zero) if the record is successfully appended, otherwise an error is returned.
Related Functions DevOpen, DevSetField
Examples
INT
FUNCTION WriteAlarmCount( INT hDevice, STRING sAlarm,
INT iCount, INT iTime )
DevAppend(hDevice);
DevSetField(hDevice, "ALARM", sAlarm);
DevSetField(hDevice, "TIME", IntToStr(iTime));
DevSetField(hDevice, "COUNT", IntToStr(iCount));
END

DevClose
Description Closes a device. Any data in the buffer is flushed to the device before it is closed. After a
device is closed, its device handle becomes invalid and cannot be used.
Syntax DevClose(hDev)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen
Examples
 DevClose 255

DevClose(hDev);

DevControl
Description Controls a dBASE or SQL device. You can pack a dBASE device to physically remove deleted
records, or re-index a dBASE device to regenerate the keys. You can issue queries to an SQL
device, or get the error status of the last SQL query.
Syntax DevControl(hDev, Type, sData)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Type .................The type of command:

0 .... Re-index the device based on the key defined in the device record (dBASE
devices only).
1 .... Pack the database file - all deleted records are removed (dBASE devices
only).
2 ..... Issue a direct SQL query to the device (SQL devices only).
3 ..... Get error status of the last SQL query (SQL devices only).
NOTE: ASCII files and printers are not supported.

sData ...............The command data, i.e. the SQL query to be issued. Used only for Type 2
commands.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevZap
Examples
! pack a dBASE file device
DevControl(hDev, 1, "");

DevCurr
Description Gets the current device handle. You can only call this function in a report, to get the handle of
the device where the report is logging. You can then use the other device functions (e.g.
DevPrint()) to access that logging device. (To get the handle of a device other than a logging
device, you must use the DevOpen() function.)
256 DevCurr

If the report is logging to a group of devices, this function will return the group handle.
However, not all device functions support group handles, e.g. you cannot read from a group of
devices.
Syntax DevCurr()

Return Value The current device handle or group handle. If no device is configured, -1 is returned.
Related Functions DevOpen, DevPrint
Examples
! Get the report device number.
hDev=DevCurr();

DevDelete
Description Deletes the current record in a dBASE database device. The record is not physically deleted, but
is marked for deletion. You can physically delete the record by packing the database with the
DevControl() function.
Syntax DevDelete(hDev)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 (zero) if the record is successfully deleted, otherwise an error is returned.
Related Functions DevOpen, DevClose, DevControl
Examples
! Delete the current record.
DevDelete(hDev);

DevDisable
Description Disables (and re-enables) a device from all access, and discards any data written to the device.
When a device is disabled, it cannot be opened, and data cannot be read from the device. Use
this function to disable logging to a database or printer.
The State argument is a toggle. A State of 1 disables the device(s), but you can then re-enable
the device(s) by repeating the function with State = 0.
Syntax DevDisable(sName, State)
 DevDisable 257

sName ..............The device name, or * (asterisk) for all devices.

State.................The disable state:

0 .... Enable the device.

1 .... Disable the device.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen
Examples
! Disable the AlarmLog device.
DevDisable("AlarmLog",1);
:
DevDisable("AlarmLog",0); ! Re-enable the device.

DevEOF
Description Gets the status of the end of file (EOF) flag for a device. When you use the DevPrev(),
DevNext(), or DevSeek() function, the start or end of the device will eventually be reached, and
the EOF flag will be set. Use this function to test the EOF flag.
Syntax DevEOF(hDev)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 1 if the EOF flag has been set, otherwise 0 (zero).
Related Functions DevOpen, DevPrev, DevNext, DevSeek, DevReadLn
Examples
hDev = DevOpen("Log", 0);
WHILE NOT DevEOF(hDev) DO
Prompt(DevGetField(hDev,"Tag"));
DevNext(hDev);
END
DevClose(hDev);
258 DevFind

DevFind
Description Searches a device for a record that contains specified data in a specified field. The search starts
at the current record and continues forward until the matched data is found or the end of the
database is reached. If the file has a keyed index, an indexed search is used.
Syntax DevFind(hDev, sFind, sField)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

sFind ...............The data to find in sField, as a string.

For SQL devices: The DevFind() function can distinguish between numbers,
strings, and dates, so you do not need to enclose the data in quote marks. Dates
and times must be in the correct format:
Date:...........YYYY-MM-DD
Time:..........HH:MM:SS
DateTime: ..YYYY-MM-DD HH:MM:SS[.F...]
(The fraction .F... is optional.)

sField............... The field name to match.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevSeek
Examples
! Find the Ice cream recipe.
Error=DevFind(hDev,"Ice cream","Recipe");
IF Error=0 THEN
! Get the recipe values.
.
.
ELSE
Prompt("Ice cream not found");
END

DevFirst
Description Finds the first record in a device.
Syntax DevFirst(hDev)
 DevFirst 259

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value The first indexed record (if the device is an indexed database), otherwise the first record in the
device.
Related Functions DevOpen, DevClose
Examples
! Find the first record.
FirstRec = DevFirst(hDev);

DevFlush
Description Flushes all buffered data to the physical device. Citect normally optimises the writing of data for
maximum performance, so use this function only if it is really necessary.
Syntax DevFlush(hDev)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevClose
Examples
! Flush device to disk.
DevFlush(hDev);

DevGetField
Description Gets field data from the current record in a device.
Syntax DevGetField(hDev, Field)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Field ................The field name, as a string of up to 10 characters. (The dBASE file format limits
all field names to a maximum of 10 characters.)

Return Value The field data (as a string). If the field is not found an empty string is returned.
Related Functions DevOpen, DevSetField
260 DevGetField

Examples
INT
FUNCTION
GetRecipe(STRING sName)
INT hDev;
hDev = DevOpen("Recipe", 0);
IF hDev >= 0 THEN
DevSeek(hDev, 1);
IF DevFind(hDev, sName, "NAME") = 0 THEN
PLC_FLOUR = DevGetField(hDev, "FLOUR");
PLC_WATER = DevGetField(hDev, "WATER");
PLC_SALT = DevGetField(hDev, "SALT");
PLC_MILK = DevGetField(hDev, "MILK");
ELSE
DspError("Cannot Find Recipe " + sName);
END
DevClose(hDev);
ELSE
DspError("Cannot open recipe database");
END
END

DevHistory
Description Renames a device file and any subsequent history files. The current device is closed and
renamed as the first history file. For example, the device file 'Templog.txt' is renamed as
'Templog.001'. If a history file 'Templog.001' already exists, it is renamed as 'Templog.002', and
so on. The next time data is written to the device, a new device file is created.
Note that if the device file has not been created (i.e. data has not been written to the device), only
existing history files are renamed. Use this function for direct control of the device history
process.
Syntax DevHistory(hDev)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevControl
Examples
! Create history file
DevHistory(hDev);
 DevInfo 261

DevInfo
Description Gets information on a device.
Syntax DevInfo(hDev, Type)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Type .................Type of information:

-n .... Name of field n (where n is any number up to the total number of fields).
For example, if there are 10 fields, -7 will return the name of field 7.
- (Total no. of fields + n) Length of field n (where n is any number up to the
total number of fields). For example, if there are 10 fields, -15 will return
the length of field 5.
0 ..... Device Name
1 ..... Format
2 ..... Header
3 ..... File Name
4 ..... Number of history files
5 ..... Form length
6 ..... Number of fields
7 ..... Disable flag
8 ..... Device type
9 ..... Record size
10.... Format number
11.... Type of history schedule:
0 ..... Event triggered
1 ..... Daily
2 ..... Weekly
3 ..... Monthly
4 ..... Yearly
12... The history period, in seconds, or week day, month or year, e.g. if history is
weekly then this is the day of the week, i.e. 1 to 7
13... Synchronisation time of day of the history, e.g. 10:00:00
262 DevInfo

14 .. The time the next history file will be created

Return Value The device information as a string if successful, otherwise an empty string is returned.
Related Functions DevControl
Examples
! Get the number of fields in a device.
NoFields=DevInfo(hDev,6);
FOR I=1 TO NoFields DO
! Get and display the name of each field.
sField=DevInfo(hDev,-I);
nLength=DevInfo(hDev,-I - NoFields);
Prompt("Field Name "+sField + "Length " + nLength:##);
END

DevModify
Description Modifies the attributes of a device. The device must be closed before you can modify a device.
This function allows you to dynamically change the file name or other attributes of a device at
run time. You can use a single device to access many files. For example, you can create a
device called Temp with a file name of TEMP.DBF. Using this function you could dynamically
change the file name to access any dBASE file.
This function is very useful in conjunction with the FormOpenFile() or FormSaveAsFile()
functions. (These functions allow the operator to select file names easily.)
When using this function, you should be careful that no other Cicode function is already using
the same device. Always check the return value of this function before opening the device or
you will destroy the data in the device to which it is already attached. Use a semaphore to
protect your Cicode.
Syntax DevModify(Name, Format, Header, FileName, Type)

Name ............... The name of the device.

Format.............A new format for the device or "*" to use the existing format.

Header.............A new header for the device or "*" to use the existing header.

*
FileName.........A new file name for the device or " " (asterisk) to use the existing filename.

Type.................A new device type:

Device Type Device

 DevModify 263

ASCII_DEV ASCII file

PRINTER_DEV Printer
dBASE_DEV dBASE file
SQL_DEV. SQL database
or -1 to use the existing device type.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevClose, DevSetField, DevInfo, DevAppend, FormOpenFile, FileSaveAsFile
Examples
! change the file name of MyDev
DevModify("MyDev", "*", "*", "c:\data\newfile.dbf", -1);

! change the fields and file name of MyDev

DevModify("MyDev", "{time}{date}{tags}", "*", "C:\DATA\OLDFILE.DBF", -
1);

! change the device to TXT file

DevModify("MyDev", "*", "*", "C:\DATA\OLDFILE.TXT", ASCII_DEV);

DevNext
Description Gets the next record in a device. If the end of the database is reached, the EOF flag is set and an
error code is returned.
Syntax DevNext(hDev)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 if the next record is read, or an error if the end of the database is reached.
Related Functions DevEOF, DevPrev
Examples
Status=0;
I = 0;
hDev = DevOpen("Log", 0);
WHILE Status = 0 DO
DspText(20 + I, 0, DevGetField(hDev,"Tag"));
I = I + 1;
Status = DevNext(hDev);
END
DevClose(hDev);
264 DevOpen

DevOpen
Description Opens a device and returns the device handle. The device must be defined in the Citect database.
If the device cannot be opened, and user error checking is not enabled, the current Cicode task is
halted.
You can use this function to return the handle of a device that is already open. The DevOpen()
function does not physically open another device - it returns the same device handle as when the
device was opened. The mode of the second open call is ignored.
To re-open an open device in a different mode, you must first close the device and then re-open
it in the new mode.
When using an ODBC driver to connect to an SQL server or database, experience has shown that
connecting only once (not closing the device) yields the best performance. ODBC connection is
very slow and if used on demand may affect your system's performance. Also some ODBC
drivers leak memory on each connection and may crash your computer after a number of re-
connects.

NOTE: If you are opening a database device in indexed mode (nMode=2), an index file will
automatically be created by Citect if one does not already exsist. If you feel a device index
has become corrupt, delete the existing index file and a new one will be created the next time
the DevOpen function is run.

Syntax DevOpen(Name, nMode)

Name ............... The name of the device.

nMode .............The mode of the open:

0 ..... Open the device in shared mode - the default mode when opening a device.
1 ..... Open the device in exclusive mode. In this mode only one user can have
the device open. The open will fail if another user has the device open in
shared or exclusive mode.
2 ..... Open the device in indexed mode. In this mode the device will be accessed
in index order. This mode is only valid if the device is a database device
and has an index configured in the Header field at the Devices form.
4 ..... Open the device in 'SQL not select' mode. If opened in this mode, you
must not attempt to read from an SQL device.
8 ..... Open the device in logging mode. In this mode the history files will be
created automatically.
16 ... Open the device in read only mode. In this mode data can be viewed, but
not written. This mode is supported only by DBF and ASCII files - it is
ignored by printers and SQL/ODBC databases.
 DevOpen 265

Return Value The device handle. If the device cannot be opened, -1 is returned. The device handle identifies
the table where all data on the associated device is stored.
Related Functions DevClose,
Examples
INT
FUNCTION
PrintRecipe(STRING sCategory)
STRING sRecipe;
INT hRecipe, hPrinter;
ErrSet(1); ! enable user error checking
hRecipe = DevOpen("Recipe", 0);
IF hRecipe = -1 THEN
DspError("Cannot open recipe");
RETURN FALSE;
END
hPrinter = DevOpen("Printer1", 0);
IF hPrinter = -1 THEN
DspError("Cannot open printer");
RETURN FALSE;
END
ErrSet(0); ! disable user error checking
WHILE NOT DevEof(hRecipe) DO
sRecipe = DevReadLn(hRecipe);
DevWriteLn(hPrinter, sRecipe);
END
DevClose(hRecipe);
DevClose(hPrinter);
RETURN TRUE;
END

DevPrev
Description Gets the previous record in a device. If the start of the database is reached, the EOF flag is set
and an error code is returned.
Syntax DevPrev(hDev)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 if the record is read successfully, or an error if the start of the database is reached.
Related Functions DevOpen, DevEOF, DevNext
Examples
Status=0;
266 DevPrev

I = 0;
hDev = DevOpen("Log", 0);
iError = DevSeek(hDev, DevSize(hDev)); ! seek to end
WHILE iError = 0 DO
DspText(20 + I, 0, DevGetField(hDev,"Tag"));
I = I + 1;
iError = DevPrev(hDev);
END
DevClose(hDev);

DevPrint
Description Prints free-format data to groups of devices. Using this function, you can write data to many
devices at the same time. You would normally use this function in a report.
Syntax DevPrint(hGrp, sData, NewLine)

hGrp ................ The device handle, or the group handle for a group of devices.

sData ...............The data to print to the group of devices.

NewLine ..........The newline flag:

0 ..... Do not insert a newline character.

1 ..... Insert a newline character.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevWriteLn, DevCurr
Examples
! Get the report device number or group number (for a group of devices).
hGrp=DevCurr();

! Print PV123 to a group of devices.

DevPrint(hGrp,"PV123="+PV123:###,1);

DevRead
Description Reads characters from a device. If the device is record-based, the current field is read. If the
device is free-format, the specified number of characters is read. If the number of characters
specified is greater than the number of characters remaining in the device, only the remaining
characters are read.
Syntax DevRead(hDev, Length)
 DevRead 267

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Length..............The number of characters to read.

Return Value The data (in string format). If the end of the device is found, an empty string is returned.
Related Functions DevOpen, DevReadLn, DevFind
Examples
! Read 20 characters from a device.
Str=DevRead(hDev,20);

DevReadLn
Description Reads data from the current record of a device until the end of the line, or end of the record. If
the device is record-based, the record number is incremented. The carriage return and newline
characters are not returned.
Syntax DevReadLn(hDev)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value The data (in string format). If the end of the device is found, an empty string is returned and the
EOF flag is set.
Related Functions DevOpen, DevRead, DevEOF, DevFind
Examples
Str=DevReadLn(hDev);

DevRecNo
Description Gets the current record number of a device. If the device is record-based, the record number
ranges from 1 to the maximum size of the file. If the device is free-format, the record number
ranges from 0 to the maximum byte size -1.
Syntax DevRecNo(hDev)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value The record number. If an error occurs getting the record number, -1 is returned.
268 DevRecNo

Related Functions DevOpen, DevSeek

Examples
! Get the current record number.
Rec=DevRecNo(hDev);
 DevSeek 269

DevSeek
Description Moves the device pointer to a specified position in the device. If the device is a database, and it
is opened in indexed mode, DevSeek will seek to the record number - not through the index. To
locate the first record in an indexed device, call the DevFirst() function.
Syntax DevSeek(hDev, Offset)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Offset ...............The offset in the device. If the device is a database device, the offset is the
record number. If the device is a binary device, the offset is in bytes (from 0 to
the maximum file size -1).

Return Value 0 (zero) if the seek was successful, otherwise an error code is returned.
Related Functions DevOpen, DevEOF, DevRecNo, DevFirst
Examples
hDev=DevOpen("Log", 0);
DevSeek(hDev,100);
DevGetField(hDev,"Tag");
! Gets the value of the "Tag" field at record 100.

DevSetField
Description Sets new field data in the current record in a device.
Syntax DevSetField(hDev, Field, sData)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Field ................The field name, as a string of up to 10 characters. (The dBASE file format limits
all field names to a maximum of 10 characters.)

sData ...............New field data, in string format. Citect converts any other data type into a string
before setting the data.

Return Value 0 (zero) if the data is successfully set, otherwise an error is returned.
Related Functions DevOpen, DevAppend, DevGetField
Examples
! Set the fields in the "Recipe" device.
270 DevSetField

hDev=DevOpen("Recipe", 0);
DevSeek(hDev, 1);
DevSetField(hDev,"Name", "WhiteBread");
DevSetField(hDev,"Flour", IntToStr(iFlour));
DevSetField(hDev,"Water", iWater:####);
DevSetField(hDev,"Salt", iSalt);
DevClose(hDev);

DevSize
Description Gets the size of a physical device.
Syntax DevSize(hDev)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value If the device is a database device, the number of records is returned. If the device is a binary
device, the number of bytes in the file is returned. If an error occurs, -1 is returned.
Related Functions DevRecNo, DevSeek
Examples
INT NoRec;
NoRec=DevSize(hDev);
! Seek to the last record.
DevSeek(hDev,NoRec);

DevWrite
Description Writes a string to a device. If the device is free-format, the data is written to the device as
specified. If the device is record-based, the data is written to the current field, and the field
pointer is moved to the next field.
Syntax DevWrite(hDev, sData)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

sData ...............The data to write, as a string.

For SQL devices: The DevWrite() function can distinguish between numbers,
strings, and dates, so you do not need to enclose the data in quote marks. Dates
and times must be in the correct format:
 DevWrite 271

Date:.......... YYYY-MM-DD
Time: ......... HH:MM:SS
DateTime:.. YYYY-MM-DD HH:MM:SS[.F...]
(The fraction .F... is optional.)

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevWriteLn
Examples
! Write PV123 to the device.
DevWrite(hDev,"PV123="+PV123:###.#);

DevWriteLn
Description Writes a string to a device. If the device is free-format, the data is written to the device,
followed by a newline character. If the device is record-based, a new record is appended to the
device and the data is written to this record. The record pointer is then moved to the next record.
Syntax DevWriteLn(hDev, sData)

hDev ................The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

sData ...............The data to write, as a string.

For SQL devices: The DevWrite() function can distinguish between numbers,
strings, and dates, so you do not need to enclose the data in quote marks. Dates
and times must be in the correct format:
Date:.......... YYYY-MM-DD
Time: ......... HH:MM:SS
DateTime:.. YYYY-MM-DD HH:MM:SS[.F...]
(The fraction .F... is optional.)

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevOpen, DevWrite
Examples
/* Write PV123 to the device followed by a newline character */
DevWriteLn(hDev,"PV123="+PV123:###.#);
272 DevZap

DevZap
Description Zaps a device. If a database device is zapped, all records are deleted. If an ASCII file is zapped,
the file is truncated to 0 (zero) length. Use this function when you want to delete all records in a
database or file without deleting the actual file.
Syntax DevZap(hDev)

hDev ................ The device handle, returned from the DevOpen() function. The device handle
identifies the table where all data on the associated device is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DevDelete
Examples
! Delete all records in the alarm log database.
hDev = DevOpen("AlarmLog", 0);
DevZap(hDev);

DLLCall
Description Calls a DLL function, and passes a string of arguments to that function. Citect converts these
arguments (where required) into the type specified in the DLLOpen() call. If an argument
cannot be converted, it is set to zero (0) or an empty string "".
You must first open the DLL with the DLLOpen() function.
Syntax DLLCall(hFunction, sArgs)

hFunction ........The DLL function handle, returned from DLLOpen().

sArgs ...............The string of arguments to pass to the DLL function. The argument string
contains all the arguments for the function, separated by commas (,). Enclose
string arguments in quote marks "", and use the string escape character (^) to put
a string delimiter within a string. This syntax is the same as the syntax for the
TaskNew()function

Return Value The result of the function, as a string.

Related Functions DLLOpen, DLLClose
Examples See DLLOpen()
 DLLClose 273

DLLClose
Description Closes the link to a DLL function, and frees the memory allocated for that function link. When
the link is closed, you cannot call the function. Citect automatically closes all function links at
shutdown.
Syntax DLLClose(hFunction)

hFunction ........The DLL function handle, returned from DLLOpen().

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DLLOpen, DLLCall
Examples See DLLOpen()

DLLOpen
Description Opens a link to a DLL function, by loading the specified DLL library into memory and attaching
it to the named function. After you open the function link, you can call the function with the
DLLCall() function. You pass the function number returned from the DLLOpen() function as an
argument in the DLLCall() function.
The best method of interfacing with a DLL function is to write a Cicode function file. This file
contains the DLLOpen() function to initialise the functions, and one Cicode function for each
DLL function, as an interface. In this way, you can hide the DLL interface in this file. Any
other Cicode function will call the Cicode interface, and the call to the DLL remains transparent
Note that DLL's must be on the path. The file extension is not required.

WARNING: You must specify the arguments to the function correctly. Citect has no way of checking the number
and type of arguments to the function. If you specify the number of arguments incorrectly, your computer
will crash. You should test your interface thoroughly before using it on a live system.

Syntax DLLOpen(sLib, sName, sArgs)

sLib ..................The DLL library name.

sName ..............The function name. An underscore (_) is required in the function name for a 'C'
function, but not for a Pascal function. When you call a DLL from a Cicode
function, sName must be the same as the name defined in the .DEF file used to
link the DLL. The file extension is not required.

sArgs................The string specifying the function arguments. The first character in the string is
the return value of the function.
274 DLLOpen

A .... Logical.
B .... IEEE 8 byte floating point number.
C .... Null terminated string. Maximum string length 255 characters.
D .... Byte counted string. First byte contains the length of the string, maximum
string length 255 characters.
H .... Unsigned 2 byte integer.
I...... Signed 2 byte integer.
J...... Signed 4 byte integer.

Return Value The DLL function handle, or -1 if the library or function could not be found or loaded.
Related Functions DLLCall, DLLClose
Examples
/* This function is called when Citect starts up, to initialise all the
DLLs that are called */

INT hAnsiUpper;
INT hGlobalAlloc;

FUNCTION
InitMyDLLs()
! Open DLL to AnsiUpper
hAnsiUpper = DLLOpen("USER.DLL", "AnsiUpper", "CC");
hGlobalAlloc = DLLOpen("Kernel", "GlobalAlloc", "IIJ");
END

/* This is the Cicode entry point into the DLL function call. This
function hides the DLL interface from the rest of Citect. */

STRING
FUNCTION
AnsiUpper(STRING sString)
STRING sResult;

sResult = DLLCall(hAnsiUpper, "^"" + sString + "^"");

RETURN sResult;
END

/* Allocate memory and return memory handle */

INT
FUNCTION
GlobalAlloc(INT Mode, INT Length)
STRING sResult;
INT hMem;
 DLLOpen 275

sResult = DLLCall(hGlobalAlloc, Mode : #### + "," + Length : ####);

hMem = StrToInt(sResult);
RETURN hMem;
END

DspAnCreateControlObject
Description Creates a new instance of an ActiveX object. If the object already exists for the given Animation
Point Number, then that object will be used, i.e. a new object will not be created, the existing
object will merely be refreshed.
An object created using this function remains in existence until the page is closed or the
associated Cicode Object is deleted.
Syntax DspAnCreateControlObject(AN, sClass, Width, Height, sEventClass)

AN....................The animation-point number.

sClass ..............The class of the object. You can use the object’s human readable name, its
program ID, or its GUID. If the class does not exist, the function will fail.

For example:

"Calendar Control 8.0" - human readable name

"MSCAL.Calendar.7" - Program ID

"{8E27C92B-1264-101C-8A2F-040224009C02}" - GUID

Width ...............The width of the ActiveX object.

Height ..............The height of the ActiveX object.

sEventClass .....The string you would like to use as the event class for the object.

Return Value The newly created object, if successful, otherwise an error is generated.
Related Functions CreateObject(),CreateControlObject()
Examples See CreateControlObject().
276 DspAnFree

DspAnFree

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Frees (removes) an AN from the current page. If an animation exists at the animation number, it
is deleted before the AN is freed. Use this function to free existing ANs or ANs created with the
DspAnNew() function. Note that the ANs are only freed in memory - the change is not
permanent.
Syntax DspAnFree(AN)

AN ...................The animation-point number.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related FunctionsDspAnNew
Examples
/* Remove AN20 from the current page. */
DspAnFree(20);

DspAnGetArea
Description Gets the area configured for an object at a specific AN (animation-point number). The area is
returned as an integer.

NOTE: This function does not return the areas of keyboard commands associated with the object.

Syntax DspAnGetArea(AN)

AN ...................The animation-point number.

Return Value The area if successful, otherwise an error is returned. If the object is configured with 'Same area
as page' checked, the area of the page will be returned. An area of 0 (zero) means no areas are
configured for the object.
Related Functions DspAnGetPrivilege,
Examples
/* Get the area configured for the object at AN60. /
DspAnGetArea(60);
 DspAnGetPos 277

DspAnGetPos
Description Gets the x and y coordinates of an AN, in pixels, relative to the top left corner of the window.
Syntax DspAnGetPos(AN, X, Y)

AN....................The animation-point number.

X ......................The variables used to store the x and y pixel coordinates of the AN, returned
from this function.

Y.......................The variables used to store the x and y pixel coordinates of the AN, returned
from this function.

Return Value 0 (zero) if successful, otherwise an error is returned. The X and Y variables are set to the AN’s
position if successful, or to -1 if an error has occurred.
Related Functions DspAnMove, DspAnInRgn, DspGetAnCur, DspGetMouse, DspGetNearestAn
Examples
/* Get the position of AN20 into X and Y. /
DspAnGetPos(20,X,Y);

DspAnGetPrivilege
Description Gets the privileges configured for an object at a specific AN (animation-point number). The
privilege is returned as an integer.

NOTE: This function does not return the privileges of keyboard commands associated with the object.

Syntax DspAnGetPrivilege(AN)

AN....................The animation-point number.

Return Value The privilege if successful, otherwise an error is returned. A privilege of 0 (zero) means no
privileges are configured for the object.
Related Functions DspAnGetArea,
Examples
/* Get the privileges of the object at AN45. /
DspAnGetPrivilege(45);
278 DspAnInfo

DspAnInfo

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Gets information on an AN - the type or state of the animation that is currently displayed.
Syntax DspAnInfo(AN, Type)

AN ...................The animation-point number.

Type.................The type of information:

0 ..... The type of animation currently displayed at the AN. The following is
returned:
0 ..... No animation is displayed.
1 ..... Colour is displayed.
2 ..... A bar graph is displayed.
3 ..... Text is displayed.
4 ..... A symbol is displayed.
5 ..... An animation symbol is displayed.
6 ..... A trend is displayed.
7 ..... A button is displayed.
8 ..... A slider is displayed.
9 ..... A plot is displayed.
1 ..... The state of the animation currently displayed. If colour is displayed, the
colour is returned. If a bar graph, trend, or symbol is displayed, the bar,
trend, or symbol name is returned. If text is displayed, the font handle is
returned.

Return Value The animation information, as a string.

Related Functions DspGetAnCur
Examples
IF DspAnInfo(25,0) = "1" THEN
/* If colour on AN 25, then get the colour */
col = DspAnInfo(25,1);
END
 DspAnInRgn 279

DspAnInRgn
Description Checks if an AN is within a region bounded by two ANs.
Syntax DspAnInRgn(AN, One, Two)

AN....................The animation-point number.

One ..................One The AN at a corner of the region.

Two ........... The AN at the opposite corner of the region.

Two ..................One The AN at a corner of the region.

Two ........... The AN at the opposite corner of the region.

Return Value 1 if the AN is within the region, or 0 (zero) if it is not.

Examples
DspGetMouse(X,Y);
DspAnMove(250,X,Y);
IF DspAnInRgn(250,20,30) THEN
Prompt("Mouse in region bounded by AN20 and AN30");
ELSE
Prompt("Mouse not in region");
END

DspAnMove

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Moves an AN to a new position. Any animation at this AN is also moved.

Syntax DspAnMove(AN, X, Y)

AN....................The animation-point number.

X ......................The x pixel coordinates of the new position.

Y.......................The y pixel coordinates of the new position.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspAnMoveRel
Examples
280 DspAnMove

DspAnMove(25,100,200);
! Moves AN25 to pixel location 100,200.

DspAnMoveRel

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Moves an AN relative to its current position. Any animation at this AN is also moved.
Syntax DspAnMoveRel(AN, X, Y)

AN ...................The animation-point number.

X ......................The number of pixels to move the AN in the x plane.

Y ......................The number of pixels to move the AN in the y plane.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspAnMove
Examples
DspAnMoveRel(25,10,20);
/* Moves AN25 by 10 pixels to the right and 20 pixels downward, relative
to its current position. */

DspAnNew

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Creates an AN at the specified x and y coordinates.

Syntax DspAnNew(X, Y)

X ......................The x pixel coordinate where the new AN is created.

Y ......................The y pixel coordinate where the new AN is created.

Return Value If successful, the new AN is returned. If the AN cannot be created, -1 is returned. If an AN
already exists at this location, that AN is returned.
Related Functions DspAnNewRel, DspAnFree
 DspAnNew 281

Examples
AN=DspAnNew(100,200);
DspSym(AN,20);
/* Displays symbol 20 at pixel location 100,200 */

DspAnNewRel

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Creates an AN at a distance of x,y pixels from a specified AN.

Syntax DspAnNewRel(AN, X, Y)

AN....................The AN used as a reference for the new AN.

X ......................The distance in the x plane (in pixels) from the reference AN to the new AN.

Y.......................The distance in the y plane (in pixels) from the reference AN to the new AN.

Return Value If successful, the new AN is returned. If the AN cannot be created, -1 is returned. If an AN
already exists at this location, that AN is returned.
Related Functions DspAnNew, DspGetAnCur
Examples
AN=DspAnNewRel(20,100,200);
/* Creates an AN at 100x and 200y pixels from AN20 */

DspBar

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a bar graph (on a graphics page) at a specified AN. To scale a tag into the correct
range, use the EngToGeneric() function.
Syntax DspBar(AN, Bar, Value)

AN....................The AN where the bar graph will be displayed.

Bar...................The name of the bar graph to display in the format <[LibName.]BarName>. If

you do not specify the library name, a bar graph from the Global library displays
(if it exists).
282 DspBar

To display a Version 1.xx bar graph, specify the bar definition (1 to 255). For
example, if you specify bar 1, Citect displays the bar graph Global.Bar001.

Value ...............The value to display on the bar graph. The value must be from 0 to 32000 to
give 0 to full-scale range on the bar.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions EngToGeneric
Examples
DspBar(25,"Bars.Loops",320);
/* Displays a value of 320 (i.e. 10%) on the loops bar (from the bars
library) at AN25. */
DspBar(25,3,320);
/* Displays a value of 320 (i.e. 10%) on bar definition 3 (Citect
Version 1.xx) at AN25. */
DspBar(26,"Loops_Bar",EngToGeneric(Tag1,0,100));
/* Displays Tag1 on the loops_bar (from the global library) at AN26.
Tag1 has an engineering scale of 0 to 100. */

DspBmp

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a bitmap at a specified AN. This function allows you to display any bitmap file at run
time. (You can get a new bitmap file from operator input or from the plant, and display it
dynamically.)
Syntax DspBmp(AN, sFile, Mode)

AN ...................The AN where the symbol will be displayed.

sFile................. The name of the bitmap (.BMP) file. The file must be in the user project path.
(Does not support 1,24 bit or OS/2 bitmaps.)

Mode ...............The mode of bitmap display:

0 ..... Erase the existing bitmap and display this bitmap.

1 ..... Do not erase the existing bitmap, just draw the new bitmap. (This mode
provides smoother animation than Mode 0, but the bitmaps must be the
same size).
2 ..... Do not erase the existing bitmap, just draw the new bitmap. This mode is
similar to mode 1, but it displays the bitmap about 3 times faster. However,
 DspBmp 283

the bitmap should not contain any transparent colour, or it will display as a
random colour. Use this mode for fast, smooth animation.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspDel
Examples
// Display the bitmap "MyImage.bmp" at AN 60
DspBMP(60, "MyImage.bmp", 0)

DspButton

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a button at a specified AN. When the button is selected, the key definition is put into
the key command line. The font, width, height, and down and repeat keys of the button are
optional. If you do not specify a width and height, the button adjusts to the size of the button
Name.
Syntax DspButton(AN, UpKey, Name, hFont, Width, Height, DownKey, RepeatKey, Style)

AN....................The animation-point number.

UpKey..............The key generated when the command button is selected (when the mouse button
is released after being clicked down). This is the default operation for
commands activated by a button.

Name................The name to display on the button.

hFont ...............The handle of the font used to display the button name. Use the DspFont()
function to create a new font and return the font handle. Use the DspFontHnd()
function to return the font handle of an existing font. The Windows button font
is used if the font is omitted or is not defined in the database.

Width ...............The width and height of the button, in pixels.

Height ..............The width and height of the button, in pixels.

DownKey .........The key generated when the mouse button is clicked down (over the command
button). Normally this parameter is not used, because most buttons are
configured to activate a command when the mouse button is released (returning
to the ‘up’ position).
284 DspButton

RepeatKey .......The key generated repetitively, whilst the mouse button is being held down (over
the command button).

Style.................A number indicating the visibility style of the button:

0 ..... NORMAL The button appears as a standard button

1 ..... BORDER_3D The button is drawn with only the 3-D border (transparent
face)
2 ..... BORDER The button is drawn with only a thin line border
3 ..... TARGET The button is totally transparent - this constitutes a screen
target

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspButtonFn, KeySetSeq, DspFont, DspFontHnd
Examples
/* Display a self-sizing button at AN20 using the default font. The
button is named "Help". When selected, the Key Code "KEY_F1" is put
into the key command line. */
DspButton(20,KEY_F1,"Help");

/* Display the same button at AN20, but in an existing font called

"BigFont". */
DspButton(20,KEY_F1,"Help",DspFontHnd("BigFont");

DspButtonFn

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a button at a specified AN. When the button is selected, a user function is called. If the
width and height are 0 (zero), then the button adjusts to the size of the button Name.
Syntax DspButtonFn(AN, UpFunction, Name, hFont, Width, Height, DownFunction, RepeatFunction)

AN ...................The animation-point number.

UpFunction .....The user function called when the command button is selected (when the mouse
button is released after being clicked down). This is the default operation for
commands activated by a button. The callback function must have no
arguments, so specify the function with no parentheses (). The callback function
must return INT as its return data type. You cannot specify a Citect in-built
function for this argument.
 DspButtonFn 285

Name................The name to display on the button.

hFont ...............The handle of the font used to display the button name. Use the DspFont()
function to create a new font and return the font handle. Use the DspFontHnd()
function to return the font handle of an existing font. The Windows button font
is used if the font is omitted or is not defined in the database.

Width ...............The width and height of the button, in pixels.

Height ..............The width and height of the button, in pixels.

DownFunction .The user function called when the mouse button is clicked down (over the
command button). Normally this parameter is not used, because most buttons
are configured to activate when the mouse button is released (returning to the
‘up’ position). The callback function must have no arguments, so specify the
function with no parentheses (). The callback function must return INT as its
return data type. You cannot specify a Citect in-built function for this argument.

RepeatFunction The user function called repetitively, whilst the mouse button is being
held down (over the command button) The callback function must have no
arguments, so specify the function with no parentheses (). The callback function
must return INT as its return data type. You cannot specify a Citect in-built
function for this argument.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspButton, DspFont, DspFontHnd
Examples
DspButtonFn(20,MyFunc,"Help",0,50,10);
! Call this function when the button is selected.
INT
FUNCTION
MyFunc()
PageDisplay("Help");
RETURN 0;
END

DspChart
Description Displays a chart at an AN. Charts are trend lines with markers on them. Values are plotted on
the chart pens. You must specify Value1, but Value2 to Value8 are optional.
If more values (than the configured pens) are specified, the additional values are ignored. If
fewer values (than the configured pens) are specified, the pens that have no values are not
displayed.
286 DspChart

You should use this function only if you want to control the display of charts directly.
Syntax DspChart(AN, Chart, Value1, Value2 ... Value8)

AN ...................The AN where the chart will be displayed.

Chart ...............The chart to display.

Value1 ............. The value to display on Pen 1 of the chart.

Value2 ... Value8 The values to display on Pen 2...Pen 8 of the chart. These values are
optional.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspDel, DspTrend
Examples
/* Using chart definition 5 at AN25, display a value of 10 on Pen1, 20
on Pen2, 30 on Pen3 and 40 on Pen4 of the chart. */
DspChart(25,5,10,20,30,40);

/* Using chart definition 6 at AN26, display a value of 100 on Pen1 and

500 on Pen2 of the chart. */
DspChart(26,6,100,500);

DspCol

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a colour at a specified AN. The colour is flooded from the AN until it finds a
boundary.
Syntax DspCol(AN, Colour)

AN ...................The animation-point number.

Colour .............The colour to display at the AN. Refer to Colour Names and Codes for a list of
colour codes.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspDel
Examples
DspCol(25,RED);
 DspCol 287

/* Displays the colour red at AN25. */

DspDel

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Deletes all objects from a specified AN.

Syntax DspDel(AN)

AN....................The animation-point number.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspDirty
Examples
DspDel(25);
! Deletes all animation at AN25.

DspDelayRenderBegin

NOTE: If you have not changed the [Page]DelayRenderAll parameter from its default (TRUE), then you do not
need to use this function.

Description Delays screen updating until DspDelayRenderEnd is called. This function should be used with
DspDelayRenderEnd() to "sandwich" Cicode that will modify the appearance of a page. The
code should be preceded by DspDelayRenderBegin(), and followed by DspDelayRenderEnd().
This will reduce screen update times, because the modifying code is given time to execute before
the page is updated with the changes, and the changes are all made in a single re-draw.
You can call this function as many times in a row as you like, as long as each is ended with a call
to DspDelayRenderEnd.
Because your display will freeze while the "sandwiched" code runs, you should try to make that
code as efficient as possible. Do not call Sleep() or any other Cicode functions that will take a
long time to run.
Do not call WinSelect within the "sandwiched" code. Do not call this function directly from the
Kernel.
Syntax DspDelayRenderBegin()

Return Value No value is returned.

288 DspDelayRenderBegin

Related Functions DspDelayRenderEnd

Examples
/* Begin delay so the following code can be executed before the images
are re-drawn. */
DspDelayRenderBegin();
DspBMP(50, "Image1.bmp", 0) ! Display the bitmap "Image1.bmp" at AN 50
DspBMP(100, "Image2.bmp", 0) ! Display the bitmap "Image2.bmp" at AN
100
DspBMP(150, "Image3.bmp", 0) ! Display the bitmap "Image3.bmp" at AN
150
DspBMP(200, "Image4.bmp", 0) ! Display the bitmap "Image4.bmp" at AN
200
DspBMP(250, "Image5.bmp", 0) ! Display the bitmap "Image5.bmp" at AN
250
/* End delay so the images can be re-drawn. */
DspDelayRenderEnd();

DspDelayRenderEnd

NOTE: If you have not changed the [Page]DelayRenderAll parameter from its default (TRUE), then you do not
need to use this function.

Description Ends the screen update delay set by DspDelayRenderBegin. This function should be used with
DspDelayRenderBegin() to "sandwich" Cicode that will modify the appearance of a page. The
code should be preceded by DspDelayRenderBegin(), and followed by DspDelayRenderEnd().
This will reduce screen update times, because the modifying code is given time to execute before
the page is updated with the changes, and the changes are all made in a single re-draw.
Because your display will freeze while the "sandwiched" code runs, you should try to make that
code as efficient as possible. Do not call Sleep() or any other Cicode functions that will take a
long time to run.
Do not call WinSelect within the "sandwiched" code. Do not call this function directly from the
Kernel.
Syntax DspDelayRenderEnd()

Return Value No value is returned.

Related Functions DspDelayRenderBegin
Examples
/* Begin delay so the following code can be executed before the images
are re-drawn. */
DspDelayRenderBegin();
DspBMP(50, "Image1.bmp", 0) ! Display the bitmap "Image1.bmp" at AN 50
 DspDelayRenderEnd 289

DspBMP(100, "Image2.bmp", 0) ! Display the bitmap "Image2.bmp" at AN

100
DspBMP(150, "Image3.bmp", 0) ! Display the bitmap "Image3.bmp" at AN
150
DspBMP(200, "Image4.bmp", 0) ! Display the bitmap "Image4.bmp" at AN
200
DspBMP(250, "Image5.bmp", 0) ! Display the bitmap "Image5.bmp" at AN
250
/* End delay so the images can be re-drawn. */
DspDelayRenderEnd();

DspDirty

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Forces Citect to update an AN. Normally, Citect updates the animation on the AN only if the
data has changed. This function tells Citect to update the AN the next time it animates the AN -
even if the data has not changed.
Use this function when you have complex animations that overlap. If two or more animations
overlap, you should use the DspDel() or DspDirty() function on their ANs, and then display them
in the same order (when they need to be updated).
Syntax DspDirty(AN)

AN....................The animation-point number.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspDel
Examples
DspDirty(20);
! Forces an update of AN20.

DspError
Description Displays an error message at the prompt AN on the operator's computer. You can disable the
error message display (of this function) by setting the Cicode execution mode in the
CodeSetMode() function.
Syntax DspError(String)

String ...............The message to be displayed.

290 DspError

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions CodeSetMode, Prompt
Examples
DspError("Error found");
! Displays "Error found" at the prompt AN.

DspFile
Description Defines the screen attributes for displaying a text file. This function defines a "window" where
the file will be displayed. You should call this function before any file-to-screen function.
You must define sequential ANs for each line of text in the display. The file is displayed starting
at the specified AN, then the next (highest) AN, and so on. You should not use proportionally-
spaced fonts, because the columns of text might not be aligned.
You would normally call this function as the entry function for a graphics page. Use the
DspFileSetName() function to specify the file to be displayed. This function is a low level
animation function - it controls exactly how the file is to display. If you just want to display a
file, use the PageFile() function.
Syntax DspFile(AN, hFont, Height, Width)

AN ...................The AN where the file display window will be positioned.

When this is set to -2, the window will be created in the Citect Kernel. However,
the hFont argument is ignored.

hFont ...............The handle for the font that is used to display the file, returned from the
DspFont() or DspFontHnd() function. The font handle identifies the table where
all data on the associated font is stored.

Height..............The maximum number of lines to display on one page of the file display
window.

Width ...............The width of the file display window, in characters.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageFile, DspFileGetInfo, DspFileGetName, DspFileScroll, DspFileSetName, DspFont,
DspFontHnd
Examples
DspFile(20,0,20,80);
/* Defines the attributes of a screen display to start at AN20, using
the default font, with a window size of 20 lines x 80 columns. */
 DspFileGetInfo 291

DspFileGetInfo
Description Gets the attributes of a file-to-screen display (used for displaying text files).
Syntax DspFileGetInfo(AN, Type)

AN....................The AN where the file display window will be located. This AN must be the
same as the AN specified with the DspFile() function.

Type .................The type of data required:

0 ..... The width of the file display window, in characters.

1 ..... The maximum number of lines that can display in one page of the file
display window.
2 ..... The file-to-screen row offset number.
3 ..... The file-to-screen column offset number.
4 ..... The number of lines in the displayed file.

Return Value The attributes of the "window" as an integer. If an incorrect AN is specified, an error is returned.
Related Functions DspFile, DspFileGetName, DspFileScroll, DspFileSetName
Examples
! Display the page number of the file display.
PageNumber=IntToStr(DspFileGetInfo(20,2)/DspFileGetInfo(20,1)+1);
DspText(12,0,"Page No "+PageNumber);

DspFileGetName
Description Gets the name of the file being displayed in the display "window". You can use this function to
display the file name on the screen.
Syntax DspFileGetName(AN)

AN....................The AN where the file display window will be located. This AN must be the
same as the AN specified with the DspFile() function.

Return Value The name of the file (as a string). If an incorrect AN is specified, an error is returned.
Related Functions DspFile, DspFileGetInfo, DspFileScroll, DspFileSetName
Examples
DspText(11,0,DspFileGetName(20));
! Displays the name of the file displayed at AN20.
292 DspFileScroll

DspFileScroll
Description Scrolls a file (displayed in the display "window") by a number of characters.
Syntax DspFileScroll(AN, Direction, Characters)

AN ...................The AN where the file display window will be located. This AN must be the
same as the AN specified with the DspFile() function.

Direction .........The direction in which to scroll:

1 ..... Left
2 ..... Right
3 ..... Up
4 ..... Down

Characters.......The number of characters to scroll. To page up or page down through the file,
scroll by the height of the file-to-screen window (returned by
DspFileGetInfo(AN, 1)).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspFile, DspFileGetInfo, DspFileGetName, DspFileSetName
Examples

Page Keyboard
Key Sequence PgUp

Command DspFileScroll(20,3,10)

Comment Scroll up 10 lines

DspFileSetName
Description Sets the name of the file to display in the display "window". You should call the DspFile()
function first (as the entry function for a graphics page) to define the attributes of the display.
You can then use the DspFileSetName() function (as a keyboard command) to display a user-
specified file. When you call this function, the specified file name is read from disk and
displayed on the screen.
Syntax DspFileSetName(AN, sName)
 DspFileSetName 293

AN....................The AN where the file display window will be located. This AN must be the
same as the AN specified with the DspFile() function.

sName ..............The name of the file to display.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspFile, DspFileGetInfo, DspFileGetName, DspFileScroll
Examples

Pages
Page Name FilePage

Entry Command DspFile(20,0,20,80)

Comment Defines a file to screen display to

commence at AN20

Page Keyboard
Key Sequence ######## Enter

Command DspFileSetName(20, Arg1)

Comment Displays a specified file on the page

DspFile(20,0,20,80);
/* Defines the file-to-screen display to commence at AN20 using the
default font, with a window size of 20 lines x 80 columns. */
DspFileSetName(20,"C:\AUTOEXEC.BAT");
! Displays file C:\AUTOEXEC.BAT.

DspFont

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Creates a font and returns a font handle. If the requested font already exists, its font handle is
returned. You can use this font handle in the functions that display text, buttons, and text files.
If the exact font size does not exist, the closest font size will be used.
Syntax DspFont(FontType, PixelSize, FgndColr, BgndColr)
294 DspFont

FontType .........The font type, for example, "Helv".

PixelSize ..........The font size, as a positive number for pixels, or a negative number for points.

FgndColr.........The foreground colour of the text.

BgndColr.........The background colour behind the text.

Return Value The font handle as an integer. If the font cannot be created, -1 is returned. The font handle
identifies the table where all data on the associated font is stored.
Related Functions DspFontHnd, DspText, DspButton, DspButtonFn, DspFile
Examples
Font=DspFont("Helv",12,"White","Red");
DspText(20,Font,"Text in Helv Font");
/* Displays "Text in Helv Font" in 12-point Helvetica font in white on
red at AN20. */

DspFontHnd

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Gets the font handle of a font that is defined in the Fonts database. You can use this font handle
in the functions that display text, buttons, and text files.
Syntax DspFontHnd(Name)

Name ............... The Font Name in the Fonts database.

Return Value The font handle as an integer. If the font cannot be found, -1 is returned. The font handle
identifies the table where all data on the associated font is stored.
Related Functions DspFont, DspText, DspButton, DspButtonFn, DspFile
 DspFontHnd 295

Examples

Fonts
Font Name BigFont

Font Type Helv

Pixel Size 24

Foreground Colour Blue

Background Colour -1

Comment Defines a font

hBigFont=DspFontHnd("BigFont");
DspText(20,hBigFont,"Text in Big Font");
/* Displays "Text in Big Font" in 24-point Helvetica font in blue on an
unchanged background at AN20. */

DspFullScreen
Description Disables or enables the full screen mode of the currently active window. This function does not
re-size the window when it is called; it merely sets the mode flag. The next time the window is
displayed, its size (on the screen) changes to reflect the setting of the flag. This function
overrides the [Animator]FullScreen parameter setting.
If [Page]DynamicSizing is turned on, a page in full screen state takes up the entire display area (assuming this does
not affect its aspect ratio), and it cannot be resized. Also, a full screen page will display without
a title bar unless Title Bar is checked in Page Properties (or was checked when the page was
created). Resizing pages can result in degraded picture quality. If this is unacceptable, you
should re-design the page using the desired resolution.
If [Page]DynamicSizing is turned off, full screen will have the same limitations as it had in
versions of Citect prior to V5.10. In other words, for a page to be displayed in full screen, the
size of the page must be the same size as the display (or bigger). If the page is smaller than the
display, the title bar will still display even if full screen mode is enabled. Check the size of the
graphic pages in CtDraw Tools|Page Attributes Dialog to make sure that it is the same as the
display resolution. For example 640x480 for VGA, 600x800 for SVGA and 1024x768 for XGA.
Syntax DspFullScreen(Mode)

Mode................Full screen mode:

0 ..... Disable full screen mode.

296 DspFullScreen

1 ..... Enable full screen mode.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinMode
Examples
/*Minimise the Window, Enable full screen mode and then maximise the
window.*/
WinMode(6);
DspFullScreen(1);
WinMode(3);

DspGetAnBottom
Description Gets the bottom extent of the object at the specified AN.
Syntax DspGetAnBottom(AN)

AN ...................The animation-point number.

Return Value The y coordinate of the bottom extent of the object at the AN. If no object exists at the AN, -1 is
returned.
Related Functions DspGetAnWidth, DspGetAnHeight, DspGetAnLeft, DspGetAnRight, DspGetAnTop,
DspGetAnExtent
Examples
nBottom = DspGetAnBottom(30);

DspGetAnCur
Description Gets the number of the current graphics AN. You should only call this function from the
database, by using one of the Page forms (for example, the Page Number, Page String, and Page
Trend forms). This function is useful for writing general functions and macros that apply to
graphics pages.
You cannot call this function from the Button or Keyboard forms.
Syntax DspGetAnCur()

Return Value The AN associated with the current record in the associated Page database. If this function is
called outside the page animation system then -1 will be returned.
 DspGetAnCur 297

Examples

Numbers
AN 20

Expression MyFunc(PV_10)

Comment Display the value of PV_10 at AN20

/* Function displays a number at the current AN and returns the value

supplied in the call */
INT
FUNCTION
MyFunc(INT value)
INT hAn, hNew;
hAn = DspGetAnCur();
hNew = DspAnNewRel(hAn, 0, 20);
DspStr(hNew, "Default", VALUE:###.#);
RETURN value;
END

DspGetAnExtent
Description Gets the extent of the object (the enclosing boundary) at the specified AN.
Syntax DspGetAnExtent(AN, Top, Left, Bottom, Right)

AN....................The AN at which the object is positioned.

Top...................A buffer that contains the top-most extent of the object.

Left...................A buffer that contains the left-most extent of the object.

Bottom .............A buffer that contains the bottom-most extent of the object.

Right ................A buffer that contains the right-most extent of the object.

Return Value 0 (zero) if successful, otherwise an error is returned. The Top, Left, Bottom, and Right arguments
contain the extents of the object, in pixels.
Related Functions DspGetAnWidth, DspGetAnHeight, DspGetAnLeft, DspGetAnRight, DspGetAnTop,
DspGetAnBottom
Examples
// Get extents at AN 25.
298 DspGetAnExtent

DspGetAnExtent(25, Top, Left, Bottom, Right);

DspGetAnFromPoint
Description Gets the AN of the object at a specified set of screen coordinates. If the X and Y co-ordinates
given are within the extents of an object, then the AN number of the object will be returned.
For example, if there is a button at coordinates (300, 140), and it is 100 wide, 50 high, this function would
return the AN if it uses X between 300 & 400 and Y between 140 and 190, such as
DspGetAnFromPoint(325,180).
(300, 140)

50
(325, 180)
100

TIP: If you are using groups and the specified coordinates point to an object that is part of a group,
the AN of the object is returned, not the AN of the group.

Example

DspGetMouse(X,Y);
// GetMouse position
AN = DspGetAnFromPoint(X,Y);
// Gets AN if mouse is over the object
Prompt("AN of object ="+AN:###);
!Displays the object's AN at the prompt line

If several objects overlap each other at the specified point, the PrevAN argument can be used to produce a list
of the associated ANs. This is achieved by using PrevAN to pass the previous result into another call of the
function until a zero return is given.
Example

INT nAn;
nAn = DspGetAnFromPoint(100,100)
WHILE nAn <> 0 DO
//Do Something
nAn = DspGetAnFromPoint(100,100,nAn);
END

Syntax DspGetAnFromPoint(X, Y, PrevAN)

X ......................The x coordinate of the screen point.

 DspGetAnFromPoint 299

Y.......................The y coordinate of the screen point.

PrevAN ............Retrieves the previous AN (in z-order) in situations where a number of objects
overlap at the specified point. The default of 0 (zero) specifies no previous AN.
A non-zero value should only ever be passed if it is the result of a previous call
to DspGetAnFromPoint.

Return Value The AN or 0 (zero) if no object exists at the point.

Related Functions DspGetNearestAn

DspGetAnHeight
Description Gets the height of the object at a specified AN.
Syntax DspGetAnHeight(AN)

AN....................The animation-point number.

Return Value The height of the object (in pixels). If no object exists at the AN, -1 is returned.
Related Functions DspGetAnWidth, DspGetAnLeft, DspGetAnRight, DspGetAnTop, DspGetAnBottom,
DspGetAnExtent
Examples
nHeight = DspGetAnHeight(30);

DspGetAnLeft
Description Gets the left extent of the object at the specified AN.
Syntax DspGetAnLeft(AN)

AN....................The animation-point number.

Return Value The x coordinate of the left extent of the object at the AN. If no object exists at the AN, -1 is
returned.
Related Functions DspGetAnWidth, DspGetAnHeight, DspGetAnRight, DspGetAnTop, DspGetAnBottom,
DspGetAnExtent
Examples
nLeft = DspGetAnLeft(30);
300 DspGetAnRight

DspGetAnRight
Description Gets the right extent of the object at the specified AN.
Syntax DspGetAnRight(AN)

AN ...................The animation-point number.

Return Value The x coordinate of the right extent of the object at the AN. If no object exists at the AN, -1 is
returned.
Related Functions DspGetAnWidth, DspGetAnHeight, DspGetAnLeftt, DspGetAnTop, DspGetAnBottom,
DspGetAnExtent
Examples
nRight = DspGetAnRight(30);

DspGetAnTop
Description Gets the top extent of the object at the specified AN.
Syntax DspGetAnTop(AN)

AN ...................The animation-point number.

Return Value The y coordinate of the top extent of the object at the AN. If no object exists at the AN, -1 is
returned.
Related Functions DspGetAnWidth, DspGetAnHeight, DspGetAnLeft, DspGetAnRight, DspGetAnBottom,
DspGetAnExtent
Examples
nTop = DspGetAnTop(30);

DspGetAnWidth
Description Gets the width of the object at a specified AN.
Syntax DspGetAnWidth(AN)

AN ...................The animation-point number.

Return Value The width of the object (in pixels). If no object exists at the AN, -1 is returned.
 DspGetAnWidth 301

Related Functions DspGetAnHeight, DspGetAnLeft, DspGetAnRight, DspGetAnTop, DspGetAnBottom,

DspGetAnExtent
Examples
nWidth = DspGetAnWidth(30);

DspGetEnv
Description Gets a page environment variable.
Syntax DspGetEnv(sName)

sName ..............The name of the variable (set using the page environment dialog)

Return Value The value of the variable (as a string).

Examples
FUNCTION
PageGroup()
PageDisplay(DspGetEnv("GroupMenu"));
END

DspGetMouse
Description Gets the x and y coordinates of the mouse position, relative to the top left corner of the window.
Syntax DspGetMouse(X, Y)

X ......................The variables used to store the x pixel coordinate of the mouse position, returned
from this function.

Y.......................The variables used to store the y pixel coordinate of the mouse position, returned
from this function.

Return Value 0 (zero) if successful, otherwise an error is returned. The X and Y variables are set to the mouse
position.
Related Functions KeyGetCursor, DspAnGetPos, DspGetNearestAn
Examples
! If the mouse cursor is at x,y pixel coordinate 43,20;
DspGetMouse(X,Y);
! Sets X to 43 and Y to 20.
302 DspGetNearestAn

DspGetNearestAn
Description Gets the AN nearest to a specified x,y pixel location.

TIP: If you are using groups and the nearest object to the specified coordinates is part of a group,
the AN of the object is returned, not the AN of the group.

Syntax DspGetNearestAn(X, Y)

X ......................The x coordinate (in pixels).

Y ......................The y coordinate (in pixels).

Return Value The animation point number (AN). A value of -1 is returned if no AN is found.
Related Functions DspGetMouse, DspAnGetPos, DspGetAnFromPoint
Examples
DspGetMouse(X,Y);
! Gets mouse position.
AN=DspGetNearestAn(X,Y);
! Gets AN nearest to the mouse.
Prompt("Mouse At AN"+AN:###);
! Displays AN nearest to the mouse.

DspGetParentAn
Description Gets the parent animation number (if any), for the specified animation number. An animation
point will have a parent animation point if it corresponds to an object in a group.
Syntax DspGetParentAn(AN)

AN ...................The animation-point number.

Return Value The parent animation point number (AN). If no parent animation exists or an invalid animation
number is passed, 0 (zero) is returned.
Related FunctionsDspGetAnCur
Examples
// Get the parent animation for object 89 (part of a symbol set)
hAn = DspGetParentAn(89);
 DspGetSlider 303

DspGetSlider

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Gets the current position (value) of a slider at an AN. You can call this function in the slider
event to find the new position of the slider.
Syntax DspGetSlider(AN)

AN....................The animation-point number.

Return Value The value of the slider from 0 to 32000. If no animation exists at the AN, -1 is returned.
Related Functions DspSetSlider
Examples
// Get the position of the slider at AN 30
nPos = DspGetSlider(30);

DspGetTip
Description Gets the tool tip text associated with an AN.
Syntax DspGetTip(AN, Mode)

AN....................The AN from which to get the tool tip text. If no object is configured at the AN,
the function will return an empty string.

Mode................0 Tool tips from all animation records configured at the AN. Tips are
concatenated with a newline character between each string. (This mode is only
used for V3.xx and V4.xx animations, and will be superseded in future releases.)

1 ..... The tool tip from the object configured at the AN.

Return Value The tool tip text (as a string). If no user tip is available, an empty string is returned.
Related Functions DspSetTip, DspTipMode
Examples
!Display the tool tip text on AN19
DspText(19, 0, DspGetTip(KeyGetCursor(), 1));
304 DspGrayButton

DspGrayButton

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Greys and disables a button. If the button is a symbol, the symbol is overwritten with a grey
mask. (When a button is greyed, it cannot be selected.) If the Disabled field in the Buttons
database is blank, the button is always enabled unless you use this function. If the Disabled field
in the Buttons database contains an expression, this function will not override the expression.
Syntax DspGrayButton(hAn, nMode)

hAn ..................The AN where the button is located.

nMode .............The mode of the operation:

0 ..... Ungrey the button.

1 (SUNK_GRAY) Recess the text or symbol (the text or symbol on the button
is recessed and shadowed).
2 (PART_GRAY) THIS MODE IS NOW OBSOLETE - IT NOW HAS THE
SAME EFFECT AS ALL_GRAY.
3 (ALL_GRAY) Mask the entire button (a grey mask displays over the face
of the button).

Return Value 0 (zero) if successful, otherwise, -1 (if no AN is found).

Related Functions DspButton, DspButtonFn, DspIsButtonGray
Examples
! Disable button at AN21
DspGrayButton(21, SUNK_GRAY);

DspInfo
Description Extracts individual pieces of object information from an AN. Each AN can have multiple
expressions associated with it, and each expression can have multiple variables associated with
it. You use an index to refer to each individual expressions or variables. Typically, you would
query the number of expressions, then the number of variables in a given expression, then the
details of a given variable tag.
NOTE: You must first create a handle to the information block using DspInfoNew().
Syntax DspInfo(hInfo, Type, Index)
 DspInfo 305

hInfo ................The object information block handle, as returned by DspInfoNew(). This handle
identifies the table (or block) where all object data is stored.

Type .................The type of data to extract:

0 ..... Object title (the name of the object type)

1 ..... Object expression text
2 ..... Object expression result text
3 ..... The variable tag name
4 ..... The raw value of the variable
5 ..... The engineering value associated with the variable
6 ..... The Cicode context. Calling DspInfo with this Type will return a string
describing the context in which the Cicode expression is contained. For
example, if it appears on the horizontal movement tab it would return
"Move X".
7 ..... The number of Cicode expressions. Calling DspInfo with this Type will
return the number of Cicode expressions associated with this animation
point.
8 ..... The number of tags in the expression. Calling DspInfo with this Type will
return the number of tags that appear in the given Cicode expression.

Index ................An index to the variable within the information block. The required index
changes according to the Type as follows:

For Types 0 to 2, 6 and 8, the index must be set to the index of the expression
that you wish to query.
For Types 3 to 5, the index must be set to the index of the tag that you wish to
query. When one of these types is used, DspInfo will query the tag in the most
recently queried expression (otherwise expression 0).
For Type 7, the index is ignored.

Return Value The object information (as a string). A blank string is returned if you specify a non-existent
expression or variable.
Related Functions DspInfoNew, DspInfoField, DspInfoDestroy
Examples
INT hInfo;
INT iRawValue;
INT iEngineeringValue;
INT iNumberOfExpressions;
INT iNumberOfTags;
306 DspInfo

INT iExpressionIndex;
INT iTagIndex;
STRING sObjectType;
STRING sExpressionText;
STRING sExpressionResult;
STRING sExpressionContext;
STRING sTagName;

hInfo = DspInfoNew(An);

IF (hInfo > -1) THEN

sObjectType = DspInfo(hInfo, 0, 0);
iNumberOfExpressions = StrToInt(DspInfo(hInfo, 7, 0));

FOR iExpressionIndex = 0 TO iExpressionIndex < iNumberOfExpressions DO

sExpressionText = DspInfo(hInfo, 1, iExpressionIndex);
sExpressionResult = DspInfo(hInfo, 2, iExpressionIndex);
sExpressionContext = DspInfo(hInfo, 6, iExpressionIndex);
iNumberOfTags = StrToInt(DspInfo(hInfo, 8, iExpressionIndex));

FOR iTagIndex = 0 TO iTagIndex < iNumberOfTags DO

sTagName = DspInfo(hInfo, 3, iTagIndex);
iRawValue = StrToInt(DspInfo(hInfo, 4, iTagIndex));
iEngineeringValue = StrToInt(DspInfo(hInfo, 5, iTagIndex));
.
.
.
END
.
.
.
END

DspInfoDestroy
Description Destroys an object information block created by DspInfoNew(). You should destroy an object
information block when you no longer need it, to free Citect resources.
When the page (with which the object is associated) is closed, Citect automatically destroys the
object information block.
Syntax DspInfoDestroy(hInfo)

hInfo ................The object information block handle, as returned by DspInfoNew(). This handle
identifies the table (or block) where all object data is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspInfo, DspInfoNew, DspInfoField, DspInfoValid
 DspInfoDestroy 307

Examples
hInfo=DspInfoNew(20);
! Do animation operation
DspInfoDestroy(hInfo);

DspInfoField
Description Obtains static and real-time data from a variable tag. You get static data from the Variable Tags
database. Two additional fields, "Raw_Value" and "Eng_Value", return dynamic real-time data
for the variable tag. To get this real-time data, you must first call the DspInfoNew() function to
get the information block handle hInfo.
Syntax DspInfoField(hInfo, sTag, sField)

hInfo ................The object information block handle, as returned by DspInfoNew(). This handle
identifies the table (or block) where all data on the object is stored.

Set this handle to 0 (zero) if you do not require real-time data.

sTag .................The name of the variable tag.

sField ...............The name of the field from which to extract the data:

Field .......... Description

Name ......... Variable Tag Name
Type .......... Data Type
Unit ........... I/O Device Name
Addr .......... Address
Raw_Zero.. Raw Zero Scale
Raw_Full... Raw Full Scale
Raw_Value Un-scaled raw value - Dynamic
Eng_Zero... Engineering Zero Scale
Eng_Full.... Engineering Full Scale
Eng_Value. Scaled engineering value - Dynamic
Eng_Units . Engineering Units
Format ....... Display Format
Comment... Variable tag comment
308 DspInfoField

Return Value The data (as a string).

Related Functions DspInfo, DspInfoNew, DspInfoDestroy
Examples
! Get the I/O Device that Variable Tag "PV123" belongs to.
IODev=DspInfoField(0,"PV123","Unit");

! Get the real-time engineering value of a tag.

hInfo=DspInfoNew(20);
sTag=DspInfo(hInfo,3,0);
EngValue=DspInfoField(hInfo,sTag,"Eng_Value");

DspInfoNew
Description Creates an object information block. Use this function with the associated low-level animation
information functions to get and process object information on an AN.
NOTE: When you have finished with the object information block, you must destroy it with the
DspInfoDestroy() function, or a fatal error could occur.
If you need simple animation help, use the InfoForm() or the InfoFormAn() functions.
Syntax DspInfoNew(hAn)

hAn ..................The AN for which object information is provided.

Return Value The object information block handle. If no object data is available, then -1 is returned.
Related Functions DspInfo, DspInfoField, DspInfoDestroy, InfoForm, InfoFormAn
Examples
/*This example creates a form, with the title "Tag Info" and a size of
25 x 5 characters. It creates an information block for the AN closest
to the mouse cursor and then extracts the name, I/O Device, and
engineering value for the first tag in the object expression.*/
INT hInfo;
STRING sTag;

hInfo=DspInfoNew(DspGetNearestAN());
IF hInfo>-1 THEN
FormNew("Tag Info",25,5,2);
sTag=DspInfo(hInfo,3,0);
FormPrompt(0,0,sTag);
FormPrompt(0,16,DspInfoField(hInfo,sTag,"Unit"));
FormPrompt(0,32,DspInfoField(hInfo,sTag,"Eng_Value"));
FormRead(0);
DspInfoDestroy(hInfo);
END
 DspInfoValid 309

DspInfoValid
Description Checks if an object information block handle is valid. An object information block handle
becomes invalid after it is destroyed, or if the user closes the page it is associated with. Use this
function if background Cicode is using the object information block, and the operator closes the
page.
Syntax DspInfoValid(hInfo)

hInfo ................The object information block handle, as returned by DspInfoNew(). This handle
identifies the table (or block) where all object data is stored.

Return Value 1 if the information block handle is valid, otherwise 0 (zero).

Related Functions DspInfoNew, DspInfoField, DspInfoDestroy
Examples
IF DspInfoValid(hInfo) THEN
Raw=DspInfoField(hInfo,sTag,"Raw_Value");
END

DspIsButtonGray

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Gets the current status of a button.

Syntax DspIsButtonGray(hAn)

hAn ..................The AN where the button is located.

Return Value The current mode of the button:

0 The button is active (not greyed).
1 (SUNK_GRAY) The button is inactive (the text or symbol on the button is recessed).
2 (PART_GRAY) THIS MODE IS NOW OBSOLETE. THE BUTTON WILL BE
INACTIVE EVEN IF PART_GRAY IS RETURNED.
3 (ALL_GRAY) The button is inactive (the entire button is masked).
Related Functions DspButton, DspButtonFn, DspGrayButton
Examples
! Check the status of the button at AN21
status = DspIsButtonGray(21);
310 DspKernel

DspKernel
Description Displays the Kernel window. You should restrict the use of this function because once you are
in the Kernel, you can execute any Cicode function with no privilege restrictions. You therefore
have total control of Citect (and subsequently your plant and equipment). Note that you can also
open the Kernel by setting the Citect [Debug]Menu parameter to 1 and, when your system is
running, selecting Kernel from the control-menu box.

WARNING: 1. You should be experienced with Citect and Cicode before attempting to use the
Kernel as these facilities are very powerful, and if used incorrectly, can corrupt your
system.
2. You should only use the Kernel for diagnostics and debugging purposes, and not
for normal Citect operation.
3. It is important to restrict access to the Kernel, because once you are in the Kernel,
you can execute any Cicode function with no privilege restrictions. You therefore
have total control of Citect (and subsequently your plant and equipment).

Syntax DspKernel(iMode)

iMode ..............The display mode of Kernel:

1 ..... Display the Kernel. . If the Kernel is already displayed and iMode=1, the
keyboard focus is changed to the Kernel.
0 ..... Hide the Kernel

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KerCmd, TraceMsg
Examples
DspKernel(1);
!Display the Citect Kernel window

DspMarkerMove
Description Moves a trend or chart marker to a specified position.
Syntax DspMarkerMove(AN, hMarker, Offset)

AN ...................The AN where the trend or chart is positioned.

hMarker...........The marker handle, as returned from the DspMarkerNew() function. The marker
handle identifies the table where all data on the associated marker is stored.
 DspMarkerMove 311

Offset ...............The offset by which to move the marker. Vertical markers have an offset from 0
(zero) to the maximum number of samples in the trend. Horizontal markers have
a offset of 0 (zero) to 32000.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspMarkerNew, OnEvent
Examples See DspMarkerNew

DspMarkerNew
Description Creates a new trend marker. A trend marker is used to show cursor values or limits on a trend.
You can use up to 10 markers on a single trend or chart.
If you add markers to a trend or chart that Citect is animating, you must repaint them using the
trend paint event (OnEvent(Window,22)). (Otherwise Citect will delete any markers displayed
when the trend is updated.)
Syntax DspMarkerNew(AN, Mode, Colour)

AN....................The AN where the trend or chart is positioned.

Mode................The mode of the marker:

0 ..... A vertical marker

1 ..... A horizontal marker

Colour..............The colour of the marker. Refer to Colour Names and Codes for a list of colour
codes.

Return Value The marker handle or -1 if the function is unsuccessful. The marker handle identifies the table
where all data on the associated marker is stored.
Related Functions DspMarkerMove, OnEvent
Examples
INT offset; ! offset of marker
INT hMarker; ! marker handle

hMarker = DspMarkerNew(40, 0, WHITE);

! create a new marker, vertical WHITE
offset = 100;
DspMarkerMove(40, hMarker, offset);
! Moves marker to offset 100

OnEvent(22, MyTrendPaint);
312 DspMarkerNew

! set trend paint event, must stop event when change pages

! this function is called when Citect updates the trend

INT
FUNCTION
MyTrendPaint()

DspMarkerMove(40, hMarker, offset);

RETURN 0;
END

DspMCI
Description Controls a multimedia device. The Media Control Interface (MCI) is a high-level command
interface to multimedia devices and resource files. MCI provides applications with device-
independent capabilities for controlling audio and visual peripherals (e.g. for playing multimedia
devices and recording multimedia resource files).
Using this function, you can control multimedia devices by using simple commands like open,
play, and close. MCI commands are a generic interface to multimedia devices. You can control
any supported multimedia device, including audio playback and recording. For a full overview
of MCI, see the Windows "Multimedia Programmer's Guide".
Syntax DspMCI(sCommand)

sCommand.......The MCI command. Refer to the Windows "Multimedia Programmer's Guide"

for further information.

Return Value A string message with the status of the MCI command.
Related Functions DspPlaySound
Examples
DspMCI("open cdaudio")
DspMCI("set cdaudio time format tmsf")
DspMCI("play cdaudio from 6 to 7")
DspMCI("close cdaudio")
/*Plays track 6 of an audio CD*/

DspMCI("open c:\mmdata\purplefi.wav type waveaudio alias finch")

DspMCI("set finch time format samples")
DspMCI("play finch from 1 to 10000")
DspMCI("close finch")
/*Plays the first 10,000 samples of a waveform audio file*/
 DspPlaySound 313

DspPlaySound
Description Plays a waveform (sound). Wave form sound files *.WAV are provided with Windows and by
third party developers, or you can record them yourself to play long (and complex) sound
sequences.
If you have a sound card, this function will return immediately and the sound will play in the
background. If you do not have a sound card, this function will not return until the sound has
finished playing - Citect will stop running, so you should not use this function unless you have a
sound card.
This function searches the [Sounds] section of the WIN.INI file for an entry with the specified
name, and plays the associated waveform. If the name does not match an entry in the WIN.INI
file, a waveform filename is assumed. The function will then search the following directories for
the waveform file (directories are listed in search order):
The current directory
The Windows directory
The Windows system directory
The directories listed in the PATH environment variable
The list of directories mapped in the network.
Syntax DspPlaySound(sSoundname, nMode)

sSoundname.....The waveform to be played. Predefined sounds (in the WIN.INI file) are:

SystemAsterisk
SystemExclamation
SystemQuestion
SystemDefault
SystemHand
SystemExit
SystemStart

nMode..............Not used - set to 0 (zero).

Return Value TRUE if successful, otherwise FALSE (if an error occurs).

Related Functions Beep
Examples
DspPlaySound("Noise.wav",0);
DspPlaySound("SystemStart",0);
314 DspRichText

DspRichText
Description Creates a Rich Text object of the given dimensions at the animation point hAn. This object can
then be used to display an RTF file (like an RTF report) called using the DspRichTextLoad
function.
Syntax DspRichText(hAn, iHeight, iWidth, iMode)

hAn ..................The AN at which the rich text object will display when the DspRichText
command is run.

iHeight.............The height of the rich text object in pixels. The height is established by
measuring down from the animation point.

iWidth .............. The width of the rich text object in pixels. The width is established by
measuring across to the right from the animation point.

iMode ..............The display mode for the rich text object. The mode can be any combination of:

0 ..... Disabled - should be used if the rich text object is to be used for display
purposes only.
1 ..... Enabled - allows you to select and copy the contents of the RTF object (for
instance an RTF report), but you will not be able to make changes.
2 ..... Read/Write - allows you to edit the contents of the RTF object. Remember,
however, that the object must be enabled before it can be edited. If it has
already been enabled, you can just enter Mode 2 as your argument. If it is
not already enabled, you will need to enable it. By combining Mode 1 and
Mode 2 in your argument (3), you can enable the object, and make it
read/write at the same time.

NOTE: .......Because the content of the rich text object is just a copy of the
original file, changes will not affect the actual file, until saved using
the DspRichTextSave function.

Return Value 0 if successful, otherwise an error is returned.

Related Functions DspRichTextLoad, PageRichTextFile
Examples
//This will produce a rich text object at animation point 57, which is
200 pixels high, and 200 pixels wide. This object will be for display
purposes only (i.e. read only)//

DspRichText(57,200,200,0);
 DspRichTextEdit 315

DspRichTextEdit
Description Enables editing of the contents of the rich text object at hAn if nEdit = TRUE, and disables
editing if nEdit = FALSE.
Syntax DspRichTextEdit(hAn, bEdit)

hAn ..................The reference AN for the rich text object.

bEdit ................The value of this argument determines whether you will be able to edit the
contents of the rich text object at hAn. Enter TRUE to enable editing, or enter
FALSE to make the contents read-only.

NOTE:....... Changes made to the contents of the object will not be saved until
the DspRichTextSave function is used.

Return Value 0 if successful, otherwise an error is returned.

Related Functions PageRichTextFile, DspRichTextEnable, DspRichTextSave
Examples
// Enables editing of the rich text object at AN 25 - if one exists.
Otherwise an error will be returned to iResult //

iResult = DspRichTextEdit(25,TRUE);

DspRichTextEnable
Description Enables the rich text object at hAn if nEnable = TRUE, and disables the object if nEnable =
FALSE. When the object is disabled, it’s contents cannot be selected or copied etc.
Syntax DspRichTextEnable(hAn, bEnable)

hAn ..................The reference AN for the rich text object.

bEnable............The value of this argument determines whether the rich text object at hAn will be
enabled or disabled. Enter TRUE to enable the object (i.e. you can select and
copy the contents of the RTF object, but you can’t make changes). Enter FALSE
to disable the object (i.e. make it display only).

Return Value 0 if successful, otherwise an error is returned.

Related Functions PageRichTextFile, DspRichTextEdit
Examples
// This line disables the rich text object at AN 25 - if one exists.
316 DspRichTextEnable

Otherwise an error will be returned to iResult //

iResult = DspRichTextEnable(25,FALSE);

DspRichTextGetInfo
Description Retrieves size information about the rich text object at animation point hAn.
Syntax DspRichTextGetInfo(hAn, iType)

hAn ..................The reference AN for the rich text object.

iType................The following size information (in pixels) can be returned about the specified
rich text object:

0 ..... Height
1 ..... Width

Return Value The requested information as a string (units = pixels).

Related Functions PageRichTextFile
Examples
! Gets the height of the rich text object at AN 25 - if one exists.
iHeight = DspRichTextGetInfo(25,0);

! Gets the width of the rich text object at AN 423.

iWidth = DspRichTextGetInfo(423,1);

DspRichTextLoad
Description Loads a copy of the file Filename into the rich text object) at animation point hAn. (The rich text
object may have been created using either the DspRichTextLoad function or the
PageRichTextFile function.)
Syntax DspRichTextLoad(hAn, sFilename)

hAn ..................The animation point at which a copy of the rich text file (e.g. an RTF report) will
display. This AN must match that of a rich text object (created using either the
DspRichText function, or the PageRichTextFile function), or the copy of the file
will not be loaded into anything, and will not display.

sFilename ........The name of the file to be copied and loaded into the rich text object at the
specified animation point. The filename must be entered in quotation marks "".
 DspRichTextLoad 317

If you are loading a copy of an RTF report, the report already have been run and
saved to a file. Remember that the filename for the saved report comes from the
File Name field in the Devices form. The location of the saved file must also be
included as part of the filename. For example, if the filename in the Devices
form listed [Data];RepDev.rtf, then you would need to enter
"[Data]\repdev.rtf" as your argument. Alternatively, you can manually enter
the path, e.g. "c:\citect\data\repdev.rtf".
If you are keeping a number of history files for the report, instead of using the
extension rtf, you must change it to reflect the number of the desired history file,
e.g. 001.

Return Value 0 if successful, otherwise an error is returned.

Related Functions DspRichText, PageRichTextFile
Examples
// This will look in the [Data] path (as specified in the Citect.ini
file), and load a copy of the file DayRep.rtf into the rich text object
at animation point 57. //
DspRichTextLoad(57,"[Data]\DayRep.rtf");

// This will look in the [Data] path (as specified in the Citect.ini
file), and load a copy of the history file DayRep.003 into the rich text
object at animation point 908. //
DspRichTextLoad(908, "[Data]\DayRep.003");

// This will load a copy of the history file f:\citect\data\DayRep.006,

into the rich text object at animation point 908. //
DspRichTextLoad(908, "f:\citect\data\DayRep.006");

DspRichTextPgScroll
Description Scrolls the contents of the rich text object displayed at hAn, by one page length in the direction
given in direction.
Syntax DspRichTextPgScroll(hAn, iDirection)

hAn ..................The reference AN for the rich text object.

iDirection ........The direction in which you want to scroll each time this function is run. You can
choose from the following:

1 ..... Left
2 ..... Right
3 ..... Up
318 DspRichTextPgScroll

4 ..... Down
8 ..... Scroll to top
16 ... Scroll to bottom

Return Value 0 if successful, otherwise an error is returned.

Related Functions PageRichTextFile, DspRichTextEdit, DspRichTextScroll
Examples
// This line scrolls the contents of the rich text object at AN 25 down
one page. Otherwise an error will be returned to iResult //
iResult = DspRichTextPgScroll(25,4);

// This line scrolls the contents of the rich text object at AN 423
right one page. Otherwise an error will be returned to iResult //
iResult = DspRichTextPgScroll(423,2);

DspRichTextPrint
Description Prints the contents of the rich text object at animation point hAn, to the port PortName.
Syntax DspRichTextPrint(hAn, sPortName)

hAn ..................The reference AN for the rich text object.

sPortName....... The name of the printer port to which the contents of the rich text object will be
printed. This name must be enclosed within quotation marks "". For example
"LPT1", to print to the local printer, or "\\Pserver\canon1" using UNC to print
to a network printer.

Return Value 0 if successful, otherwise an error is returned.

Related Functions DspRichText, FileRichTextPrint
Examples
! This lines prints
DspRichTextPrint(25,"LPT1:");

DspRichTextSave
Description Saves the contents of the rich text object at animation point hAn, to the file Filename.
Syntax DspRichTextSave(hAn, sFilename)
 DspRichTextSave 319

hAn ..................The reference AN for the rich text object.

sFilename ........The name under which the contents of the rich text object will be saved. This
name must be enclosed within quotation marks "", and must include the
destination path. For example "[Data]\saved.rtf".

Return Value 0 if successful, otherwise an error is returned.

Related Functions DspRichText, PageRichTextFile, DspRichTextLoad, DspRichTextEdit
Examples
// These lines show two different ways of saving the contents of the
rich text object (at AN 25) to file DayRep.rtf//
DspRichTextSave(25,"[Data]\DayRep.rtf");
DspRichTextSave(25,"c:\citect\data\DayRep.rtf");

DspRichTextScroll
Description Scrolls the contents of the rich text object displayed at hAn, in the direction given in direction, by
the number of lines/units given in amount. Remember that the height of a line varies according to
the font used, therefore if you need to scroll absolute distances, it might be advisable to use the
DspRichTextPgScroll function.
Syntax DspRichTextScroll(hAn, iDirection, iAmount)

hAn ..................The reference AN for the rich text object.

iDirection ........The direction in which you want to scroll each time this function is run. You can
choose from the following:

1 ..... Left
2 ..... Right
3 ..... Up
4 ..... Down
8 ..... Scroll to top
16.... Scroll to bottom

iAmount ...........The amount by which you would like to scroll each time this function is run.

Enter the number of lines (for a vertical direction) or units (for a horizontal
direction) by which you would like to scroll.

Return Value 0 if successful, otherwise an error is returned.

320 DspRichTextScroll

Related Functions PageRichTextFile, DspRichTextEdit, DspRichTextPgScroll

Examples
DspRichTextScroll(25,4,8);
DspRichTextScroll(423,2,1);
See PageRichTextFile.

DspRubEnd
Description Ends the rubber band selection, and returns the coordinates of the rubber band selection. The
meaning of the cx and cy values depend on the nMode you specify in the DspRubStart()
function.
Syntax DspRubEnd(x,y, cx, cy)

x,y ....................The x and y coordinates of the start position.

cx, cy ...............The x and y coordinates of the end position.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspRubStart, DspRubMove, DspRubSetClip
Examples See DspRubStart().

DspRubMove
Description Moves the rubber band selection to the new position. You must first call the DspRubStart()
function to start the rubber band selection, and DspRubEnd() function to form the rubber band
selection.
This function will erase the existing rubber band and then redraw it in the new position. You would normally move
the rubber band by mouse input, but you can get input from the keyboard or any other Cicode to
control the rubber band.
Syntax DspRubMove(x,y)

x,y ....................The x and y coordinates of the current position.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspRubStart, DspRubEnd, DspRubSetClip
Examples See DspRubStart().
 DspRubSetClip 321

DspRubSetClip
Description Sets the clipping region for the rubber band display. If you enable the clipping region, the rubber
band will not move outside of the clip region. This allows you to restrict the rubber band to
within some constrained region. (For example, to prevent an operator from dragging the rubber
band outside of the trend display when zooming the trend.)
You must call this function (to enable the clipping region) before you can start the rubber band
selection (with the DspRubStart() function).
Syntax DspRubSetClip(x1,y1,x2,y2)

x1,y1,x2,y2.......The x and y coordinates of the clipping region.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspRubStart, DspRubEnd, DspRubMove
Examples
// Set the clipping region to a rectangle starting at 100, 100 to 200,
300
DspRubSetClip(100, 100, 200, 300);
// Start the rubber band display with clipping mode on
DspRubStart(x, y, 4);

DspRubStart
Description Starts the rubber band selection. Call this function when the left mouse button is pressed - the
rubber band is displayed at the starting position. Call the DspRubEnd() function to end the
selection, when the mouse button is released. The DspRubMove() function moves the selection
to the new position.
This function is used by the trend templates for the trend zoom function. Use the rubber band
functions whenever you want the operator to select a region on the screen or display a dynamic
rectangle on the screen.
You can only display one rubber band per page. If you display a second rubber band, the first
rubber band is erased. To move a rubber band with the mouse, use the OnEvent() function to get
notification of the mouse movement, and then the DspRubMove() function. Because these are
generic rubber-band display functions, you can get input from the keyboard, Cicode variables,
the I/O Device, and the mouse.
Syntax DspRubStart(x,y, nMode)

x,y ....................The x and y coordinates of the start position.

nMode..............The mode of the rubber banding operation:

322 DspRubStart

0 ..... cx,cy as absolute pixel positions

1 ..... cx,cy in pixels relative to x,y
2 ..... (x,y) always top left to (cx,cy)
4 ..... the clipping region.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspRubEnd, DspRubMove, DspRubSetClip, OnEvent
Examples See also the ZOOM.CI file in the Include project for further examples.

INT xRub,yRub,cxRub,cyRub;

/* Call this function on left mouse button down. */

FUNCTION
StartSelection()
INT x,y;
DspGetMouse(x,y); ! Get the current mouse position
DspRubStart(x,y,0); ! Start the rubber banding
OnEvent(0,MouseEvent); ! Attach mouse move event
END

/* Call this function on left mouse button up. */

FUNCTION
EndSelection()
! Stop the rubber banding and get sizes into the ..Rub variables
DspRubEnd(xRub,yRub,cxRub,cyRub);
OnEvent(0,0); ! Stop mouse move event
END

INT
FUNCTION
MouseEvent()
INT x,y;
DspGetMouse(x,y); ! Get mouse position
DspRubMove(x,y); ! Move the rubber band
RETURN 0
END

DspSetSlider

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Sets the current position of a slider at the specified AN. You can use this function to move a
slider, and adjust the value of the variable associated with the slider.
 DspSetSlider 323

Syntax DspSetSlider(AN, nPos)

AN....................The animation-point number.

nPos.................The position of the slider from 0 to 32000 where 0 is the zero position of the
slider and 32000 if full position of the slider.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspGetSlider
Examples
// Set the position of the slider at AN 30 to 1/2 scale
DspSetSlider(30, 16000);

DspSetTip
Description Sets tool tip text associated with an AN. Any existing text associated with the AN will be
replaced with the new text.
Syntax DspSetTip(AN, sText)

AN....................The animation-point number.

sText ................The tool tip text to set for the AN.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspGetTip, DspTipMode
Examples
!Set a tool tip for AN19
DspSetTip(19, "Start Slurry Pump");

DspSetTooltipFont
Description Sets the font for tool tip text.
The parameter [Animator]TooltipFont also specifies the tool tip font. The parameter is checked
at startup, and if it is set, the font is set accordingly. You can then use DspSetTooltipFont() to
override the parameter until the next time you start Citect.
Syntax DspSetTooltipFont(sName, nPointSize, sAttribs)
324 DspSetTooltipFont

sName.............. The name of the Windows font to be used, enclosed by quotation marks " ". A
value for this parameter is required, however specifying an empty string "" will
set the tooltip font to the default of MS Sans Serif.

nPointSize........The size of the font in points. If you do not specify a value, the point size
defaults to 12.

sAttribs ............ A string specifying the format of the font. Use one or all of the following,
enclosed by quotation marks " ":

B to specify Bold

I to specify Italics

U to specify Underline
If you don't specify a value for this parameter, it will default to an empty string
and no formatting will be applied.

Return Value No return value

Related Functions DspGetTip, DspTipMode
Examples
!Set the tool tip font to Bold, Italic, Times New Roman, with a point
size of 12
DspSetTooltipFont("Times New Roman", 12, "BI");

DspStatus
Description Determines whether the object at the specified AN will be greyed (hatch pattern) in the event of
a communication failure.
Syntax DspStatus(AN, nMode)

AN ...................The animation-point number.

nMode .............0 Switch off the error status

1 ..... Grey the object (with a hatch pattern)

Return Value 0 (zero) if successful, otherwise an error is returned.

Examples
DspStatus(67, 1)
// Disable the animation at AN 67
 DspStr 325

DspStr

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a string at a specified AN.

Syntax DspStr(AN, sFont, sText)

AN....................The AN where the text will be displayed.

sFont................The name of the font that is used to display the text. The Font Name must be
defined in the Fonts database. If the font is not found, the default font is used.

sText ................The text to display.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspText
Examples
DspStr(25,"RedFont","Display this text");
/* Displays "Display this text" using "RedFont" at AN25. "RedFont" must
be defined in the Fonts database. */

DspSym

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a symbol at a specified AN. If the symbol number is 0, any existing symbol (at the
AN) is erased.
Syntax DspSym(AN, Symbol, Mode)

AN....................The AN where the symbol will be displayed.

Symbol .............The name of the symbol to display in the format <[LibName.]SymName>. If you
do not specify the library name, a symbol from the Global library will display (if
it exists).

To display a Version 1.xx symbol, specify the symbol number (0 to 255). For
example, if you specify symbol 1, Citect displays the symbol Global.Sym001.

Mode................The mode of symbol display:

0 ..... Erase the existing symbol and display this symbol.

326 DspSym

1 ..... Do not erase the existing symbol, just draw the new symbol. (This mode
provides smoother animation than Mode 0, but the symbols must be the
same size).
2 ..... Do not erase the existing symbol, just draw the new symbol. This mode is
similar to mode 1, but it displays the symbol about 3 times faster.
However, the symbol should not contain any transparent colour, or it will
display as a random colour. Use this mode for fast, smooth animation.
If you omit the mode, the default mode is 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspDel
Examples
! Erase the existing symbol and then display the centrifuge symbol (from
the pumps library) at AN25.
DspSym(25,"Pumps.Centrifuge");
! Erase the existing symbol and then display Citect Version 1.xx symbol
2 at AN25.
DspSym(25,2);
! Do not erase the existing symbol, just display the tank symbol (from
the global library) at AN26.
DspSym(26,"Centrifuge",1);

DspSymAnm

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Animates a series of symbols at an AN. Sym1 displays first, then Sym2, Sym3 . . . Sym8 and then
Sym1 displays again, etc. When the next symbol in the sequence is displayed, the current symbol
is not erased, but is overwritten to provide a smoother animation. The symbols should all be the
same size.
The frequency of changing the symbols is determined by the [Page]AnmDelay parameter.
You only need to call this function once to keep the animation going. To stop the animation call
the DspDel() function, or call this function again with different symbols (to change the
animation).
Syntax DspSymAnm(AN, Sym1, Sym2 ... Sym8)

AN ...................The AN where the animation will occur.

 DspSymAnm 327

Sym1 ................The name of the symbol to animate in the format <[LibName.]SymName>. If

you do not specify the library name, a symbol from the Global library will
display (if it exists).

To animate a Version 1.xx symbol, specify the symbol number (0 to 255). For
example, if you specify symbol 1, Citect displays the symbol Global.Sym001.
Not all symbols have to be specified. If for example, only two symbols are to
display, specify Sym1 and Sym2.

Sym2 ... Sym8...The name of the symbol to animate in the format <[LibName.]SymName>. If
you do not specify the library name, a symbol from the Global library will
display (if it exists).

To animate a Version 1.xx symbol, specify the symbol number (0 to 255). For
example, if you specify symbol 1, Citect displays the symbol Global.Sym001.
Not all symbols have to be specified. If for example, only two symbols are to
display, specify Sym1 and Sym2.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspSym
Examples
DspSymAnm(25,"Pumps.Centrifuge","Pumps.Floatation");
! Alternately displays the centrifuge symbol and the flotation
symbol(from the pumps library) at AN25.
DspSymAnm(25,4,7);
! Alternately displays Citect Version1.xx symbols 4 and 7 at AN25.

DspSymAnmEx

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Animates a series of symbols at an AN. Sym1 displays first, then Sym2, Sym3 . . . Sym9 and then
Sym1 displays again, etc. When the next symbol in the sequence is displayed, the current symbol
is not erased, but is overwritten to provide a smoother animation. The symbols should all be the
same size.
The frequency of changing the symbols is determined by the [Page]AnmDelay parameter.
You only need to call this function once to keep the animation going. To stop the animation call
this function again with a different Mode.
Syntax DspSymAnmEx(AN, Mode, Sym1, Sym2 ... Sym9)

AN....................The AN where the animation will occur.

328 DspSymAnmEx

Mode ...............The mode of the display:

-1.... Soft animation. The background screen (a rectangular region beneath the
symbol) is restored with the original image. Any objects that are within the
rectangular region are destroyed when the background is restored. Use this
mode when each animation symbol is a different size.
0 ..... Overlap animation. The background screen (beneath the symbol) is not
erased - the next symbol is displayed on top. Transparent colour is
supported in this mode, allowing for symbol overlap. For this mode to
display correctly, each symbol must be the same size.
1 ..... Animate animation. The background screen (beneath the symbol) is not
erased - the next symbol is displayed on top. This mode provides the
fastest animation. For this mode to display correctly, each symbol must be
the same size. Transparent colour is not supported in this mode.
8 ..... Stops the animation at the last symbol displayed. Use this mode where you
want to freeze your animation at the end of the sequence.
16 ... Stops the animation at the current symbol displayed. Use this mode where
you want to freeze your animation instantly.

Sym1................ The name of the symbol to animate in the format <[LibName.]SymName>. If

you do not specify the library name, a symbol from the Global library will
display (if it exists).

To animate a Version 1.xx symbol, specify the symbol number (0 to 255). For
example, if you specify symbol 1, Citect displays the symbol Global.Sym001.
Not all symbols have to be specified. If for example, only two symbols are to
display, specify Sym1 and Sym2.

Sym2 ... Sym9 .. The name of the symbol to animate in the format <[LibName.]SymName>. If
you do not specify the library name, a symbol from the Global library will
display (if it exists).

To animate a Version 1.xx symbol, specify the symbol number (0 to 255). For
example, if you specify symbol 1, Citect displays the symbol Global.Sym001.
Not all symbols have to be specified. If for example, only two symbols are to
display, specify Sym1 and Sym2.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspSym
Examples
DspSymAnmEx(25,0,"Pumps.Centrifuge","Pumps.Floatation");
! Alternately displays the centrifuge symbol and the flotation
symbol(from the pumps library) at AN25.
 DspSymAnmEx 329

DspSymAnmEx(25,0,4,7);
! Alternately displays Citect Version1.xx symbols 4 and 7 at AN25.
DspSymAnmEx(25,2,"Pumps.Centrifuge","Pumps.Floatation");
! Stop the cycle and display the current symbol.

DspSymAtSize

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays a symbol at the specified scale and offset from the AN position.
By calling this function continuously, you can move symbols around the screen and change their
size and shape, to simulate trippers, elevators, and so on. You change the PositionX, PositionY
values to change the position of the symbol, the SizeX, SizeY values to change its size, or the
symbol itself to change its shape.
You can only use this function at a blank AN, or an AN with a symbol defined without symbols
configured. The AN must not be attached to any other animation object.
Syntax DspSymAtSize(AN, sSym, PositionX,PositionY, SizeX,SizeY, Mode)

AN....................The AN where the symbol will be animated.

sSym.................The name of the symbol to display, move, or size. If sSym is 0 (zero), any
existing symbol at the AN is erased.

PositionX,PositionY The horizontal and vertical offset position (from the AN) of the symbol
(in pixels).

SizeX,SizeY ......The horizontal and vertical scaling factors for the symbol (0 - 32000). For
example, if PositionX and PositionY are both 32000, the symbol is displayed at
its normal size. Note that symbols can only be reduced in size.

Mode................The mode of symbol display:

0 ..... Erase the existing symbol and display this symbol.

1 ..... Do not erase the existing symbol, just draw the new symbol. (This mode
provides smoother animation than Mode 0, but the symbols must be the
same size).
2 ..... Do not erase the existing symbol, just draw the new symbol. This mode is
similar to mode 1, but it displays the symbol about 3 times faster.
However, the symbol should not contain any transparent colour, or it will
display as a random colour. Use this mode for fast, smooth animation.
If you omit the mode, the default mode is 0.
330 DspSymAtSize

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspAnMove, DspAnMoveRel, DspSym, DspSym
Examples
! Display tripper moving in x axis at normal size.
DspSymAtSize(21, "lib.tripper", x, 0, 32000, 32000, 0);
! Display elevator going up and down.
DspSymAtSize(22, "lib.elevator", 0, y, 32000, 32000, 0);
! Display can getting bigger and smaller.
DspSymAtSize(23, "lib.can", 0, 0, size, size, 0);

DspText

NOTE: This function is only used for V3.xx and V4.xx animations, and will be superseded in future releases.

Description Displays text at an AN. This function does the same operation as DspStr(), however it uses a
font number rather than a font name.
Syntax DspText(AN, Font, Text)

AN ...................The AN where the text will be displayed.

Font .................The font number that is used to display the text. (To use the default font, set to -
1.)

Text.................. The text to display.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspStr, DspFont, DspFontHnd
Examples
/* Displays "Display this text" at AN25 using the font defined as
BigFont. */
hBigFont=DspFontHnd("BigFont");
DspText(25,hBigFont,"Display this text");

DspTipMode
Description Switches the display of tool tips on or off. This function overrides the setting in the
[Page]TipHelp parameter.
Syntax DspTipMode(nMode)
 DspTipMode 331

nMode..............The display mode:

0 ..... Off
1 ..... On
2 ..... Toggle the tool tip mode
3 ..... Do not change the mode, just return the current value

Return Value The old mode.

Related Functions DspSetTip, DspGetTip
Examples
DspTipMode(1); //Switch on tool tips

DspTrend
Description Displays a trend at an AN. Values are plotted on the trend pens. You must specify Value1, but
Value2 to Value8 are optional. If more values (than configured pens) are specified, the
additional values are ignored. If fewer values (than configured pens) are specified, the pens that
have no values are not displayed.
DspTrend() is optimised so that it will not display the trend until a full set of samples has been
collected. For example, if you have defined 100 samples for your trend, the trend will not
display until value 100 is entered.
You should use this function only if you want to control the display of trends directly. If you use
the standard Trends (defined in the Trends database) this function is called automatically.
Syntax DspTrend(AN, Trend, Value1, Value2 ... Value8)

AN....................The AN where the trend will be displayed.

Trend ...............The name of the trend to display in the format <[LibName.]TrnName>. If you
do not specify the library name, a trend from the Global library will display (if it
exists).

To display a Version 1.xx trend, specify the trend number (0 to 255). For
example, if you specify trend 1, Citect displays the trend Global.Trn001.

Value1..............The value to display on Pen 1 of the trend.

Value2 ... Value8 The values to display on Pen 2...Pen 8 of the trend (optional).

Return Value 0 (zero) if successful, otherwise an error is returned.

332 DspTrend

Related Functions DspDel

Examples
/* Using the main_loop trend (from the trends library) at AN25, display
a value of 10 on Pen1, 20 on Pen2, 30 on Pen3 and 40 on Pen4 of the
trend. */
DspTrend(25,"Trends.Main_Loop",10,20,30,40);

/* Using trend definition 5 (Citect Version 1.xx) at AN25, display a

value of 10 on Pen1, 20 on Pen2, 30 on Pen3 and 40 on Pen4 of the trend.
*/
DspTrend(25,5,10,20,30,40);

/* Using the loops trend (from the global library) at AN26, display a
value of 100 on Pen1 and 500 on Pen2 of the trend. */
DspTrend(26,"Loops",100,500);

/* Display a trend configured with 100 samples immediately. The data

for the first 100 samples is stored in an array - MyData[100]. On first
display, grab all the data and call DspTrend().*/
FOR i = 0 to 100 DO
DspTrend(hAn, "Loops", MyData[i]);
END
// display new samples every 300ms
WHILE TRUE DO
// Shift MyData down and grab new sample
TableShift(MyData, 100, 1);
MyData[99] = MyFastData;
DspTrend(hAn, "Loops", MyData[99]);
SleepMS(300);
END

/* Display a trend configured with 100 samples immediately. Dummy data

is pushed into the first 100 samples to fill the trend. Once these
values are entered, the trend will be updated each time a new sample
value is entered.*/
// fill up the trend.
FOR i = 0 to 100 DO
DspTrend(hAn, "Loops", 0);
END
// display new samples every 300ms
WHILE TRUE DO
DspTrend(hAn, "Loops", MyFastData);
SleepMS(300);
END
 DspTrendInfo 333

DspTrendInfo
Description Get information on a trend definition.
Syntax DspTrendInfo(hTrend, Type)

hTrend .............The name of the trend in the format <[LibName.]TrnName>. If you do not
specify the library name, a trend from the Global library is assumed.

To get information on a Version 1.xx trend, specify the trend number (0 to 255).
For example, if you specify trend 1, Citect obtains information from the trend
Global.Trn001.

Type .................Type of trend info:

0 ..... Type of trend:

....... 0 = line
....... 1 = bar
1 ..... Number of samples in trend
2 ..... Pixel height of trend
3 ..... Pixel width of trend
4 ..... Number of trend pens
11.... Colour of Pen 1
12.... Colour of Pen 2
13.... Colour of Pen 3
14.... Colour of Pen 4
15.... Colour of Pen 5
16.... Colour of Pen 6
17.... Colour of Pen 7
18.... Colour of Pen 8

Return Value The trend information (as an integer). If Pen Colour (Types 11 - 18) is requested from a bar
trend, the return value is -1.
Related Functions DspTrend
Examples
! get the number of samples for the main_loop trend (from the trends
library).
nSamples = DspTrendInfo("Trends.Main_Loop", 1);
334 DspTrendInfo

! get the number of samples for trend 3 (Citect Version 1.xx).

nSamples = DspTrendInfo(3, 1);

DumpKernel
Description Dumps Kernel data to the KERNEL.DAT file.
Syntax DumpKernel(iMode, sName)

iMode ..............The Kernel data to dump:

0x0001 .......Dump general statistics

0x0002 .......Dump the task
0x0004 .......Dump the I/O Device
0x0008 .......Dump the driver
0x0010 .......Dump netstat
0x0020 .......Dump the table
0x0040 .......Dump the queue
0x4000 .......Dump in verbose mode
0x8000 .......Dump all the kernel data

sName.............. The queue or table name(empty for all queues or tables). Only valid if
iMode=0x0001 or 0x0040

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspKernel, KerCmd, TraceMsg
Examples
DumpKernel(0x8000, "");
!Dump all the Kernel data

EngToGeneric
Description Gets a variable in the Citect generic scale format. Citect uses this scale to display trends. Citect
calls this function automatically for trends defined in the project. However, to display a trend by
using Cicode, you must call this function.
Syntax EngToGeneric(Value, EngLow, EngHigh)
 EngToGeneric 335

Value................The value to convert to the Citect generic scale format.

EngLow............The engineering units zero scale.

EngHigh ..........The engineering units full scale.

Return Value The variable (in the range 0 - 32000).

Related Functions DspBar, DspTrend
Examples
/* Using trend definition 5 at AN20, display the value of Tag1 on Pen1
of the trend. Tag1 has an engineering scale of 0 to 100. */
DspBar(20,5,EngToGeneric(Tag1,0,100));

EnterCriticalSection
Description Requests permission for the current thread to have access to a critical section. If the critical
section is already being accessed by another thread (using the EnterCriticalSection() function),
the current thread will be granted access when the other thread relinquishes ownership using the
LeaveCriticalSection() function.
Once a thread has ownership of a critical section, it can access the same section repeatedly (using
the EnterCriticalSection() function each time). Remember, however, that LeaveCriticalSection()
must be called once for each EnterCriticalSection() used.
Syntax EnterCriticalSection(sName)

sName ..............The name of the critical section. The name must be entered in quotation marks.

Return Value This function does not return a value.

Related Functions LeaveCriticalSection
Examples
/* Request access to critical section, execute code and relinquish
ownership of critical section. */

FUNCTION
MyCriticalFunction()
EnterCriticalSection("MyCritical");
// critical code is placed here
LeaveCriticalSection("MyCritical");
END
336 ErrCom

ErrCom
Description Gets the communication status for the current Cicode task. You can call this function in reports,
Cicode that is associated with an object, and in any Cicode task.
Syntax ErrCom()

Return Value 0 (zero) if all I/O Device data associated with the task is valid, otherwise an error is returned.
Related Functions CodeSetMode
Examples
IF ErrCom()<>0 THEN
Prompt("I/O Device data is bad");
END
In a report format:

{CICODE}
IF ErrCom()<>0 THEN
PrintLn("This Report contains bad data");
END
{END}

ErrDrv
Description Gets a protocol-specific error message and native error code.
Syntax ErrDrv(sProtocol, sField, nError)

sProtocol .........The Citect protocol.

sField............... The field in the PROTERR.DBF database:

PROTOCOL
MASK
ERROR
MESSAGE
REFERENCE
ACTION
COMMENT

nError ............. The protocol specific error code. This field must be a variable as it also the place
where the returned error code is stored.
 ErrDrv 337

Since the first 34 specific error codes are standard for all protocols, Citect may
add 'masking' to make the error code unique. For example, if an I/O Device
returns errors 1 to 10 (which are already used), the driver may add 0x100000 to
it's error codes. When this function is called, the mask will be removed before
the result is returned to this variable.

Return Value The error message (as a string), or an empty string ("") if the error is not found. The error code
is returned into the nError variable.
Related Functions ErrInfo, ErrHelp
Examples
// Get the error message and number associated with error 108
nError = 108;
sError = ErrDrv("TIWAY", "MESSAGE", nError);

ErrGetHw
Description Gets the current error status for a hardware device.
Syntax ErrGetHw(Device)

Device..............The hardware device number:

0 ..... Generic
1 ..... LAN
2 ..... Cicode
3 ..... Animation
4 ..... Reports Server
5 ..... Alarms Server
6 ..... Trends Server
7 ..... I/O Server
IODevNo + 512 I/O Device

Return Value The error.

Related Functions ErrSetHw
Examples
Error=ErrGetHw(3);
! Sets Error to the current error status for the animation device.
IF Error=0 THEN
338 ErrGetHw

DspText(4,0,"");
ELSE
DspText(4,0,"Hardware error");
END

ErrHelp
Description Displays information about a hardware error.
Syntax ErrHelp(Error)

Error ............... The Cicode hardware error string (as returned by ErrMsg()).

Return Value 0 (zero) if successful, otherwise an error (274) is returned.

Related Functions ErrInfo, IsError, ErrMsg
Examples
! Invokes the Citect Help with help on the hardware alarm.
iResult = ErrHelp(ErrMsg(IsError()));

ErrInfo
Description Gets extended error information on the last error that occurred.
Syntax ErrInfo(Type)

Type.................The type of error information.

0 .... Animation number where the error occurred.

Return Value The error information.

Examples
! Get the animation number where the last error occurred
hAn = ErrInfo(0);
 ErrLog 339

ErrLog
Description Logs a message to the Citect system log file.
This function is useful for logging errors in user functions, and for debugging user functions.
The Citect system log file 'SYSLOG.DAT' is created in the local Windows directory of the
computer, eg C:\WINDOWS.
Syntax ErrLog(Message)

Message ...........The message to log. This field can also contain control (such as /n) and
formatting characters.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DebugMsg, DebugMsgSet, CodeTrace, TraceMsg, Halt
Examples
FUNCTION
MyFunc(INT Arg)
IF Arg<0 THEN
ErrLog("Invalid arg in Myfunc");
Halt();
END
END

ErrMsg
Description Gets the error message associated with a hardware error.
Syntax ErrMsg(nError)

nError..............The hardware error number returned from the IsError() function.

Return Value The error message (as a string). A null value is returned if nError is not in the range of Cicode
Errors.
Related Functions IsError, ErrHelp, ErrInfo, ErrTrap
Examples
//Get the message of the last hardware error
sMsg = ErrMsg(IsError());
340 ErrSet

ErrSet
Description Sets the error-checking mode. When Mode is set to 0 and a fatal error occurs, Citect halts the
execution of the Cicode task that caused the error, and generate a hardware error.
You can perform error checking by setting Mode to 1 and using the IsError() function to trap
errors. When the type of error is determined, you can control what happens under particular
error conditions.
The operation of the ErrSet() function is unique to each Cicode task. If you enable user error
checking for one task, it does not enable error checking for any other tasks. Note : This has
changed from previous versions of Citect where this feature used to effect all Cicode tasks.
Syntax ErrSet(Mode)

Mode ...............Error-checking mode:

0 .... Citect will check for errors.

1 .... The user must check for errors.
The default Mode is 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions IsError, ErrSetHw, ErrSetLevel
Examples
ErrSet(1);
Test=Var/0;
Error=IsError();
! Sets Error to 273 (divide by zero).

ErrSetHw
Description Sets the hardware error status for a hardware device. Call this function to generate a hardware
error.
Syntax ErrSetHw(Device, Error)

Device .............The hardware device number:

0 ..... Generic
1 ..... LAN
2 ..... Cicode
3 ..... Animation
 ErrSetHw 341

4 ..... Reports Server

5 ..... Alarms Server
6 ..... Trends Server
7 ..... I/O Server
IODevNo + 512 I/O Device

Error................The error code.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ErrSet
Examples
ErrSetHw(4,273);
! Generates a divide by zero error (273) on the report device.
ErrSetHw(3,0)
! Resets any error on the animation device.

ErrSetLevel
Description Sets the nesting error level to enable Citect error checking inside a nested function (when Citect
error checking has been disabled). This function returns the old error level and sets a new error
level.
The nesting error level is incremented every time the ErrSet(1) function is called.
Syntax ErrSetLevel(Level)

Level ................The nesting error level.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ErrSet
Examples
! ErrorLevel 0 defaults to ErrSet(0) - enables Citect error-checking.
FUNCTION
MainFn()
ErrSet(1);
! ErrorLevel 1 - disables Citect error checking.
Fn1();
ErrSet(0);
! Enables Citect error checking.
END
FUNCTION
Fn1()
342 ErrSetLevel

ErrSet(1);
! ErrorLevel 2 - disables Citect error checking.
Test=Var/0;
Error=IsError();
! Sets Error to 273 (divide by zero).
Fn2();
ErrSet(0); ! Enables Citect error checking.
END
FUNCTION
Fn2()
OldErrorLevel=ErrSetLevel(0);
! Sets nesting error level to 0 to enable Citect error-checking.
Test=Var/0;
! Cicode halts and a hardware alarm is generated.
ErrSetLevel(OldErrorLevel)
! Resets nesting error level to disable Citect error-checking.
END

ErrTrap
Description Generates an error trap. If Citect error checking is enabled, this function will generate a
hardware error and may halt Cicode execution (see bHalt argument). If user error checking is
enabled, the user function specified in OnEvent(2,Fn) is called.
Syntax ErrTrap(Error, bHalt)

Error ............... The error number to trap.

bHalt ...............Determines whether the Cicode execution will be halted.

0 ..... Cicode execution is not halted

1 ..... Cicode execution is halted

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ErrSetHw, ErrSet, ErrSetLevel, OnEvent
Examples
IF Tag=0 THEN
ErrTrap(273); ! Traps a divide by zero error.
ELSE
Value=10/Tag;
END
 Exec 343

Exec
Description Executes an application or PIF file. The application or command starts up and continues to run
in parallel with Citect.
This function can return while the application is still starting up, so you should use the Sleep()
function to allow the application enough time to start.
Syntax Exec(Command, Mode)

Command ........The operating system command to execute.

Mode................The mode of the window:

1 ..... Normal
3 ..... Maximised
6 ..... Minimised
If you do not enter a mode, the default mode is 1.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Sleep
Examples
Exec("Pbrush");
! Starts up the Paintbrush application with a normal window.
Exec("C:\COMMAND.COM /c mkdir test");
! Uses the DOS shell to create a new directory

ExecuteDTSPkg
Description Loads and executes a DTS (Data Transformation Services) package which initiates data transfer
and transformations between OLE DB data sources.
A DTS package is created using the DTS utility provided in Microsoft SQL Server 7.0. It can be
saved in a COM structured file, a Microsoft Repository, or in an SQL Server Database.
All except the first of this function's parameters are optional, and their use will depend on your
needs.
Syntax ExecuteDTSPkg(sFileOrSQLSvrName, sPkgName, sParam1, ... , sParam5, sPkgPwd,
sPkgVer, sLogFile, sSQLSvrUsr, sSQLSvrPwd)

sFileOrSQLSvrName The path and name of the file containing the package
(for file-based packages), or the SQL Server name (for SQL Server stored
packages).
344 ExecuteDTSPkg

sPkgName........The package name.

For file-based packages where only one package is stored in a file, you can
ignore this parameter, as the package name defaults to the name of the file.
If the package has been named differently to the file, or a file contains more than
one package, you must specify the package name.
You must also specify the package name for SQL Server stored packages.

sParam1, ... , sParam5 Five optional variables which may be used as global variables
within the DTS package. The variables must be named Param1, Param2, Param3,
Param4, and Param5.

sPkgPwd..........The package password.

The creator of the DTS package may have implemented a password to prevent
unauthorised users from executing it. In this case, you must specify the package
password. If no password has been implemented, you can omit this parameter.

sPkgVer ...........The package version. If you don't specify a version, the most recent version is
used.

sLogFile .......... An optional path and name for a log file. The log file can track activity such as:

File DTS package detected

SQL DTS package detected

Package initialised successfully

Package executed successfully

Package execution failed

sSQLSvrUsr..... The user name providing access to the SQL Server where the DTS package is
stored. A user's account on the SQL Server consists of this user name and, in
most cases, a password.

This parameter also determines which method is used to load the package.
If sSQLSvrUsr is specified, the package is assumed to be an SQL Server stored
package. In this case, the package is loaded using the LoadFromSQLServer()
method. Otherwise, the package is file-based and LoadFromStorageFile() is
called.

sSQLSvrPwd....The password providing access to the SQL Server, if the user's account on the
server requires a password.

Return Value 0 (zero) if the package was executed successfully, otherwise a DTS error number is returned.
 ExecuteDTSPkg 345

Examples
/* File-based package with one package per file, where the package name
is the same as the file name.*/
iResult = ExecuteDTSPkg("c:\dtspackages\package.dts");

/*SQL Server stored package with additional parameters */

iResult = ExecuteDTSPkg("Server1", "TestPackage", "Param1", "Param2",
"Param3", "Param4", "Param5", "Fred", "1", "c:\packages\PkgLog.txt",
"jsmith", "secret");

Exp
Description Calculates the exponential of a number (natural logarithm base e).
Syntax Exp(Number)

Number ............Any number.

Return Value The exponential of Number (to the base e).

Related Functions Log
Examples
Variable=Exp(1);
! Sets Variable to 2.7182...

Fact
Description Calculates the factorial of a number.
Syntax Fact(Number)

Number ............Any number.

Return Value The factorial of Number.

Examples
Variable=Fact(6);
! Sets Variable to 720 (i.e. 720=1x2x3x4x5x6).
346 FileClose

FileClose
Description Closes a file. All data written to the file is flushed to disk when the file is closed, and the file
number becomes invalid.
Syntax FileClose(File)

File .................. The file number.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FileOpen
Examples
File=FileOpen("C:\Data\Report.Txt","r");
:
! Do file operations.
:
! Close the file.
FileClose(File);

FileCopy

Description *
Copies a file. You can use the DOS wild card characters ( ) and (?) to copy groups of files. In
asynchronous Mode, this function will return immediately and the copy will continue in the
background. Unless you are accessing to the floppy drive, copying files does not interfere with
the operation of other Citect tasks, because this function is time-sliced.
Syntax FileCopy(Source, Dest, Mode)

Source .............The name of the source file to copy.

Dest .................The name of destination file to copy to. To copy a file to the printer, specify the
name as "LPT1.DOS".

Mode ...............The copy mode:

0 ..... Normal
1 ..... Copy only if the file time is different.
2 ..... Copy in asynchronous mode.
Multiple modes can be selected by adding them together (for example, set Mode
to 3 to copy in asynchronous mode if the file time is different).
 FileCopy 347

Return Value 0 (zero) if successful, otherwise an error is returned. However, if you copy in asynchronous
mode, the return value does not reflect the success or failure of the copy, because the function
returns before the actual copy is complete.
Related Functions FileDelete
Examples
! Copy Report.Txt to Report.Bak.
FileCopy ("C:\Data\Report.Txt", "C:\Data\Report.Bak",0);

/* Copy AlarmLog.Txt to AlarmLog.Bak only if the file time is different.

Copy in the background. */
FileCopy ("AlarmLog.Txt", "AlarmLog.Bak",1+2);

FileDelete
Description Deletes a file.
Syntax FileDelete(Name)

Name................The name of the file to delete.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FileCopy
Examples
! Delete old report file.
FileDelete("C:\Data\Report.Txt");

FileEOF
Description Determines if the end of the file has been reached.
Syntax FileEOF(File)

File ..................The file number.

Return Value 1 if the end of file has been reached, otherwise 0 (zero).
Related Functions FileSeek
Examples
WHILE NOT FileEOF(File) DO
Str=FileReadLn(File);
348 FileEOF

END

FileExist
Description Checks if a file exists. If the return value is 1, the file exists.
Syntax FileExist(Name)

Name ............... The name of the file to check.

Return Value TRUE (1) if the file exists, otherwise FALSE (0).
Related Functions FileOpen
Examples
! Check if the file exists
IF FileExist("C:\Data\Report.Txt") THEN
! The file exists
END

FileFind
Description Finds a file that matches a specified search criteria. To find a list of files, you must first call this
function with the required path and mode (to find the first file), then call the function again with
an empty path and a mode of 0 (to find the remaining files). After the last file is found, an empty
string is returned.
Syntax FileFind(sPath, nMode)

sPath ...............The name of the file to check.

nMode .............The type of file to check:

0 ..... Normal file

1 ..... Read-only file
2 ..... Hidden file
4 ..... System file
8 ..... Volume ID
16 ... Subdirectory
32 ... Archived file
 FileFind 349

Return Value The full path and filename. If no files are found, an empty string is returned.
Related Functions FileOpen, FileSplitPath, FileMakePath
Examples
! Search for all dBase files in the run directory and make a backup
sPath = FileFind("[run]:\*.dbf", 0);
WHILE StrLength(sPath) > 0 DO
FileSplitPath(sPath, sDrive, sDir, sFile, sExt);
sBak = FileMakePath(sDrive, sDir, sFile, "BAK");
FileCopy(sPath, sBak, 0);

! Find the next file

sPath = FileFind("", 0);
END

FileGetTime
Description Gets the time on a file.
Syntax FileGetTime(File)

File ..................The file number.

Return Value The file time of the file (in the Citect time/date variable format).
Related Functions FileOpen, FileClose, FileSetTime
Examples
File = FileOpen("[data]:report.txt", "r");
! Get the time of the file
iTime = FileGetTime(File);
FileClose(File);

FileMakePath
Description Creates a file path string from individual components.
Syntax FileMakePath(sDrive, sDir, sFile, sExt)

sDrive ..............The disk drive.

sDir..................The directory string.

sFile.................The file name (without the extension).

350 FileMakePath

sExt..................The file extension.

Return Value The full path as a string.

Related Functions FileSeek, FileFind, FileSplitPath
Examples See FileFind()

FileOpen
Description Opens a file and returns a file number that can be used by other file functions.
You can also use this function to check if a file exists, by opening the file in read-only mode. A
return value of -1 indicates that the file cannot be opened.
Syntax FileOpen(Name, Mode)

Name ............... The name of the file to open.

Mode ...............The mode of the opened file:

"a" .. Append mode. Allows you to append to the file without removing the end
of file marker. The file cannot be read. If the file does not exist, it will be
created.
"a+" Append and read modes. Allows you to append to the file and read from it.
The end of file marker will be removed before writing and restored when
writing is complete. If the file does not exist, it will be created.
"r"... Read-only mode. Allows you to (only) read from the file. If the file does
not exist or cannot be found, the function call will fail.
"r+" Read/write mode. Allows you to read from, and write to, the file. If the
file exists (before the function is called), its contents will be destroyed. If
the file does not exist or cannot be found, the function call will fail.
"w" . Write mode, file is truncated. Opens an empty file for writing. If the file
exists (before the function is called), its contents will be destroyed. If the
file does not exist or cannot be found, the function call will fail.
"w+"Read/write mode, file is truncated. Opens an empty file for both reading
and writing. If the file exists (before the function is called), its contents
will be destroyed. If the file does not exist or cannot be found, the function
call will fail.

Return Value The file number. If the file cannot be opened, -1 is returned and the code is halted.
Related Functions FileClose, FileRead, FileReadLn, FileWrite, FileWriteLn
 FileOpen 351

Examples
! Open a file in read-only mode.
File=FileOpen("C:\Data\Report.Txt","r");

FilePrint
Description Prints a file on a device.
Syntax FilePrint(Devicename, Filename)

Devicename .....The name of the target device.

Filename..........The name of the file to print on the device.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FileOpen, FileClose, FileWrite, FileWriteLn
Examples
! Print a data file on the system printer.
FilePrint("Printer_Device","Data.txt");

FileRead
Description Reads a number of characters from a file. The string can contain less characters than requested if
the end of file is reached. A maximum of 255 characters can be read in each call.
Syntax FileRead(File, Length)

File ..................The file number.

Length..............The number of characters to read.

Return Value The text from the file (as a string).

Related Functions FileOpen, FileClose, FileReadLn
Examples
WHILE NOT FileEOF(File) DO
Str=FileRead(File,20);
END
352 FileReadBlock

FileReadBlock
Description Reads a number of characters from a file. The buffer can contain less characters than requested
if the end of file is reached. A maximum of 255 characters can be read in each call. The data
should be treated as a binary data and should not be passed to string functions. You may use
StrGetChar() function to extract each character from the buffer, or pass the buffer to another
function which will accept binary data.
Syntax FileReadBlock(File, Buffer, Length)

File .................. The file number.

Buffer...............The buffer to return the binary data. This may be a string or a string packed with
binary data. The string terminator is ignored and the length argument specifies
the number of characters to write.

Length .............The number of characters to read.

Return Value The number of characters read from the file. When the end of the file is found 0 will be returned.
If an error occurs -1 will be returned and IsError() will return the error code.
Related Functions FileOpen, FileClose, FileRead, FileWriteBlock, StrGetChar
Examples
// read binary file and copy to COM port
length = FileReadBlock(File, buf, 128);
WHILE length > 0 DO
ComWrite(hPort, buf, length, 0);
length = FileReadBlock(File, buf, 128);
END

FileReadLn
Description Reads a line from a file. Up to 255 characters can be returned. The carriage return and newline
characters are not returned. If the line is longer than 255 characters, the error overflow (code
275) is returned - you should call this function again to read the rest of the line.
Syntax FileReadLn(File)

File .................. The file number.

Return Value The text, as a string.

Related Functions FileOpen, FileClose, FileRead
Examples
 FileReadLn 353

sLine = FileReadLn(hFile);
! do stuff with the string
WHILE IsError() = 275 DO
! read the rest of the line
sLine = FileReadLn(hFile);
! do stuff with the rest of the line
END

FileRename
Description Renames a file.
Syntax FileRename(Oldname, Newname)

Oldname ..........The original name of the file.

Newname .........The new name of the file.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FileCopy, FileDelete
Examples
! Rename REPORT.TXT as REPORT.OLD.
FileRename("C:\Data\Report.Txt","C:\Data\Report.Old");

FileRichTextPrint
Description Prints the rich text file sFilename to the printer given by sPortname.
Syntax FileRichTextPrint(sFilename, sPortName)

sFilename ........The filename of the rich text format file. The filename must be entered in
quotation marks "".

Remember that the filename for a saved report comes from the File Name field
in the Devices form. The location of the saved file must also be included as part
of the filename. For example, if the filename in the Devices form listed
[Data];RepDev.rtf, then you would need to enter "[Data]\repdev.rtf" as your
argument. Alternatively, you can manually enter the path, e.g.
"c:\citect\data\repdev.rtf".
If you are keeping a number of history files for the report, instead of using the
extension rtf, you must change it to reflect the number of the desired history file,
e.g. 001.
354 FileRichTextPrint

sPortName....... The name of the printer port to which the rich text file will be printed. This
name must be enclosed within quotation marks "". For example "LPT1", to
print to the local printer, or "\\Pserver\canon1" using UNC to print to a
network printer.

Return Value 0 if successful, otherwise an error is returned.

Related Functions PageRichTextFile, DspRichTextPrint
Examples
// This would print the file [Data]\richtext.rtf to LPT1. Remember that
the [Data] path is specified in the Citect.ini file. The file
richtext.rtf is the name of the output file for the report, as specified
in the Devices form. //
iResult = FileRichTextPrint("[Data]\richtext.rtf","LPT1:");

// This would print the file f:\citect\data\richtext.rtf to LPT1. The

file richtext.rtf is the name of the output file for the report, as
specified in the Devices form. //
iResult = FileRichTextPrint("f:\citect\data\richtext.rtf","LPT1:");

FileSeek
Description Moves the file pointer to a specified position in a file.
Syntax FileSeek(File, Offset)

File .................. The file number.

Offset ............... The offset in bytes, from 0 to the maximum file size -1.

Return Value The new file position, or -1 if an error occurs.

Related Functions FileSize
Examples
! Seek to the start of the file.
FileSeek(File,0);
 FileSetTime 355

FileSetTime
Description Sets the time on a file.
Syntax FileSetTime(File, iTime)

File ..................The file number.

iTime................The new file time, in the Citect time/date variable format.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FileOpen, FileClose, FileGetTime
Examples
File = FileOpen("[data]:report.txt", "r+");
! set the file to the current time
FileSetTime(File,TimeCurrent());
FileClose(File);

FileSize
Description Gets the size of a file.
Syntax FileSize(File)

File ..................The file number.

Return Value The size of the file, in bytes.

Related Functions FileSeek
Examples
! Get the size of the file.
Size=FileSize(File);

FileSplitPath
Description Splits a file path into individual string components. You enter the full path string as sPath. The
individual components of the path name are returned in the arguments sDrive, sDir, sFile, and
sExt.
Syntax FileSplitPath(sPath, sDrive, sDir, sFile, sExt)
356 FileSplitPath

sPath ...............The full path string.

sDrive ..............The disk drive.

sDir ................. The directory string.

sFile................. The file name (without the extension).

sExt..................The file extension.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FileSeek, FileFind, FileMakePath
Examples See FileFind()

FileWrite
Description Writes a string to a file. The string is written at the current file position.
Syntax FileWrite(File, String)

File .................. The file number.

String...............The string to write.

Return Value The number of characters written.

Related Functions FileOpen, FileClose, FileWriteLn
Examples
! Write to the file.
FileWrite(File,"Data");

FileWriteBLock
Description Writes a string or buffer to a file. The data is written at the current file position. You may create
the binary data by using the StrSetChar function or by reading the data from some other function.
This function is similar to the FileWrite() function however you specify the length of data to
write to the file. The FileWrite() function will send the data to the file until the sting terminator is
found. FileWriteBlock() will ignore any string terminator and copy the length of bytes to the file.
This allows this function to be used for binary data transfer
Syntax FileWriteBLock(File, Buffer, Length)
 FileWriteBLock 357

File ..................The file number.

Buffer...............The data to write to the file. This may be a string or a string packed with binary
data. The string terminator is ignored and the length argument specifies the
number of characters to write.

Length..............The number of characters to write. The maximum number of characters you may
write in one call is 255. (If you use a string without a terminator in a function
that expects a string, or in a Cicode expression, you could get invalid results.)
To use the string to build up a buffer, you do not need the terminating 0 (zero).

Return Value The number of characters written to the file. If an error occurs -1 will be returned and IsError()
will return the error code.
Related Functions FileOpen, FileClose, FileWrite, FileReadBlock, StrSetChar
Examples
STRING buf;

FOR I = 0 TO 20 DO
StrSetChar(buf, I, I); // put binary data into string
END
! Write binary data to the file.
FileWrite(File, buf, 20);

FileWriteLn
Description Writes a string to a file, followed by a newline character. The string is written at the current file
position.
Syntax FileWriteLn(File, String)

File ..................The file number.

String ...............The string to write.

Return Value The number of characters written (including the carriage return and newline characters).
Related Functions FileOpen, FileClose, FileWrite
Examples
! Write a line to the file.
FileWriteLn(File,"Line of file data");
358 FmtFieldHnd

FmtFieldHnd
Description Gets the handle of a field in a format template. You can then use the field handle in the
FmtGetFieldHnd() and FmtSetFieldHnd() functions. By using a handle, you only need to
resolve the field name once and then call other functions as required (resulting in improved
performance.)
Syntax FmtFieldHnd(hFmt, Name)

hFmt ................ The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

Name ............... The field name.

Return Value The handle of the format template field, or -1 if the field cannot be found.
Related Functions FmtGetFieldHnd, FmtSetFieldHnd
Examples
!Resolve names at startup.
hName=FmtFieldHnd(hFmt,"Name");
hDesc=FmtFieldHnd(hFmt,"Desc");

!Set field data.

FmtSetFieldHnd(hFmt,hName,"CV101");

FmtGetField
Description Gets field data from a format template. Use this function to extract data after a call to
StrToFmt().
Syntax FmtGetField(hFmt, Name)

hFmt ................ The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

Name ............... The field name.

Return Value The data (as a string). If the field does not contain any data, an empty string will be returned.
Related Functions StrToFmt, FmtSetField, FmtToStr
Examples
StrToFmt(hFmt,"CV101 Raw Coal Conveyor");
Str=FmtGetField(hFmt,"Name");
! Str will contain "CV101".
 FmtGetFieldHnd 359

FmtGetFieldHnd
Description Gets field data from a format template. Use this function to extract data after a call to
StrToFmt(). This function has the same effect as FmtGetField(), except that you use a field
handle instead of the field name.
Syntax FmtGetFieldHnd(hFmt, hField)

hFmt ................The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

hField ..............The field handle.

Return Value The data (as a string). If the field does not contain any data, an empty string will be returned.
Related Functions StrToFmt, FmtFieldHnd
Examples
StrToFmt(hFmt,"CV101 Raw Coal Conveyor");
hField=FmtFieldHnd(hFmt,"Name");
Str=FmtGetField(hFmt,hField);
! Str will contain "CV101".

FmtOpen
Description Creates a format template. After you create a template, you can use it for formatting data into
strings or extracting data from a string. To format a template, use the same syntax as a device
format, i.e. {<name>[,width[,justification]]}.
Syntax FmtOpen(Name, Format, Mode)

Name................The name of the format template.

Format.............The format of the template, as {<name>[,width[,justification]]}.

Mode................The mode of the open:

0 ..... Open the existing format.

1 ..... Open a new format.

Return Value The format template handle, or -1 if the format cannot be created.
Related Functions FmtClose
Examples
360 FmtOpen

hFmt=FmtOpen("MyFormat","{Name}{Desc,20}",0);
FmtSetField(hFmt,"Name", "CV101");
FmtSetField(hFmt,"Desc","Raw Coal Conveyor");
Str =FmtToStr(hFmt);
! Str will contain "CV101 Raw Coal Conveyor".

FmtSetField
Description Sets data in a field of a format template. After you have set all the fields, you can build the
formatted string with the FmtToStr() function.
Syntax FmtSetField(hFmt, Name, Data)

hFmt ................ The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

Name ............... The field name.

Data.................Field data.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FmtGetField, FmtToStr
Examples
hFmt=FmtOpen("MyFormat","{Name}{Desc, 20}",0);
FmtSetField(hFmt,"Name", "CV101");
FmtSetField(hFmt,"Desc","Raw Coal Conveyor");
Str =FmtToStr(hFmt);
! Str will contain "CV101 Raw Coal Conveyor".

FmtSetFieldHnd
Description Sets data in a field of a format template. After you have set all the fields, you can build the
formatted string with the FmtToStr() function. This function has the same effect as
FmtSetField() except that you use a field handle instead of the field name.
Syntax FmtSetFieldHnd(hFmt, hField, Data)

hFmt ................ The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

hField .............. The field handle.

 FmtSetFieldHnd 361

Data.................Field data.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FmtFieldHnd, FmtToStr, FmtSetField
Examples
hField=FmtFieldHnd(hFmt,"Name");
FmtSetFieldHnd(hFmt,hField,"CV101");

FmtToStr
Description Builds a formatted string from the current field data (in a format template).
Syntax FmtToStr(hFmt)

hFmt ................The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

Return Value The formatted string as defined in the format description.

Related Functions StrToFmt
Examples
! Get the formatted string.
Str=FmtToStr(hFmt);

FormActive
Description Checks if a form is currently active (displayed on the screen). This function is useful when
forms are being displayed in asynchronous mode and another Cicode task is trying to access the
form.
Syntax FormActive(hForm)

hForm ..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

Return Value TRUE (1) if the form is active or FALSE (0) if it is not.
Related Functions FormDestroy, FormNew
Examples See FormDestroy.
362 FormAddList

FormAddList
Description Adds a text string to a list box or combo box. You should call this function only after the
FormNew() function, and immediately after either the FormComboBox() or the FormListBox(),
and before the FormRead() function. The text is added at the end of the list box or combo box.
To add text to a form that is already displayed, use the FormListAddText() function, and use the
FormListSelectText() function to highlight text on the list.
Syntax FormAddList(sText)

sText ................ The text string to add to the list box or combo box.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormNew, FormRead, FormListBox, FormComboBox, FormListAddText, FormListDeleteText,
FormListSelectText
Examples See FormComboBox and FormListBox

FormButton
Description Adds a button to the current form. You can add buttons that run callback functions (specified in
Fn) to perform any actions you need, as well as the standard buttons - an [OK] button to save the
operator's entries and close the form, and a [Cancel] button to close the form but discard the
changes.
You should call this function only after the FormNew() function and before the FormRead()
function. The button is added to the form at the specified column and row position. The width
of the button is automatically sized to suit the text.
Syntax FormButton(Col, Row, sText, Fn, Mode)

Col...................The number of the column in which the button will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the button in
column 8, enter 7.

Row .................The number of the row in which the button will be placed. Enter a number from
0 (row 1) to the form height - 1. For example, to place the button in row 6, enter
5.

sText ................ The text to display on the button.

Fn ....................The callback function to call when the button is selected. Set to 0 to call no
function. Note that the Fn parameter must be of type INT and the callback
function cannot contain a blocking function.
 FormButton 363

Mode................Button mode:

0 ..... Normal button. When this button is selected the callback function is called.
1 ..... OK button. When this button is selected, the form is closed, and all
operator-entered data is copied to buffers (specified by the other form
functions). FormRead() returns 0 (zero) to indicate a successful read. The
callback function specified in Fn is called. Note that this mode destroys the
form.
2 ..... Cancel button. When this button is selected, the form is closed and
operator-entered data is discarded. FormRead() returns with an error 299.
The callback function specified in Fn is called. Note that this mode
destroys the form.

Return Value The field handle if the button is successfully added, otherwise -1 is returned.
Related Functions FormNew, FormRead
Examples
! Create a form, add buttons and then display the form on the current
page
FUNCTION
FnMenu()
FormNew("MENU",20,6,1);
FormButton(0 ,4 ," FIND ", FindMenu, 0);
FormButton(10,4 ," TAG ", ShowTag, 0);
FormButton(0 ,5 ," CANCEL ", KillForm, 0);
FormButton(10,5 ," GOTO ", GotoPg, 0);
FormRead(0);
END

FormCheckBox
Description Adds a check box to the current form. The check box is a form control that allows the operator
to make individual selections. Each check box can be either checked (true) or cleared (false).
You should call this function only after the FormNew() function and before the FormRead()
function. The check box is added to the form at the specified column and row position. The
width of the button is automatically sized to suit the text.
Syntax FormCheckBox(Col, Row, sText, sBuf)

Col ...................The number of the column in which the check box will be placed. Enter a
number from 0 (column 1) to the form width - 1. For example, to place the
check box in column 8, enter 7.
364 FormCheckBox

Row .................The number of the row in which the check box will be placed. Enter a number
from 0 (row 1) to the form height - 1. For example, to place the check box in
row 6, enter 5.

sText ................ The text associated with the check box.

sBuf .................The string buffer in which to put the state of the check box. You should initialise
this buffer to the state of the check box. When the form returns, this buffer will
contain either '1' or '0' if the box is checked.

Return Value The field handle if the check box is successfully added, otherwise -1 is returned.
Related Functions FormNew, FormRead
Examples
! Create a form, add check boxes, and display the form.
! The operator may select none or all of the check boxes.
FUNCTION
FnMenu()
STRING sNuts, sCherrys, sChocolate;
sNuts = "1";
sCherrys = "0";
sChocolate = "1";

FormNew("IceCream",20,6,1);
FormCheckBox(2 ,2,"Nuts", sNuts);
FormCheckBox(2, 3,"Cherrys", sCherrys);
FormCheckBox(2 ,4,"Chocolate", sChocolate);
FormRead(0);

If sNuts = "1" THEN

! add the nuts
END
IF sCherrys = "1" THEN
! add the cherrys
END
IF sChocolate = "1" THEN
! add the chocolate
END
END

FormComboBox
Description Adds a combo box to the current form. A combo box is a form control that allows the operator
to type a selection or make a single selection from a text list.
You should call this function only after the FormNew() function and before the FormRead()
function. The combo box is added to the form at the specified column and row position with the
 FormComboBox 365

specified width and height. If more items are placed in the list than the list can display, a scroll
bar displays (to scroll to the hidden items).
Use the FormAddList() function to add items for display in the list box. If the form is already
displayed, you can use the FormListAddText() and FormListSelectText() functions to add (and
highlight) text in the list box.
Syntax FormComboBox(Col, Row, Width, Height, sBuf, Mode)

Col ...................The number of the column in which the combo box will be placed. Enter a
number from 0 (column 1) to the form width - 1. For example, to place the
combo box in column 8, enter 7.

Row..................The number of the row in which the combo box will be placed. Enter a number
from 0 (row 1) to the form height - 1. For example, to place the combo box in
row 6, enter 5.

Width ...............The width of the list box, which should be wide enough to display your widest
item. Items wider than the list box are clipped.

Height ..............The height of the list box (the number of items that can be seen in the list box
without scrolling).

sBuf..................The string buffer in which to store the selected item. The sBuf parameter can
also hold the starting selection for the Combo box. For example if you set the
sBuf string to "HELLO" before calling FormComboBox, HELLO will be
displayed in the box upon opening the form.

Mode................The mode in which to create the combo box:

0 ..... Sort the combo box elements alphabetically.

1 ..... Place elements in combo box in the order they were added.

Return Value The field handle if the combo box is successfully added, otherwise -1 is returned.
Related Functions FormNew, FormRead, FormAddList, FormListAddText, FormListSelectText, FormListBox
Examples
! Create a form, add combo box and then display the form
! the operator may type in or select one of the items from the list
FUNCTION
FnMenu()
STRING sBuf;

FormNew("Select Item",20,6,1);
FormComboBox(2 ,2, 15, 5, sBuf, 1);
FormAddList("Item One");
FormAddList("Item two");
366 FormComboBox

FormAddList("Item three");
FormRead(0);

! sBuf should contain the selected item or entered text

END

FormCurr
Description Gets the form and field handles for the current form and field. You should call this function only
from within a callback function. You can then use the same callback function for all forms and
fields, regardless of how the boxes, buttons, etc. on the forms are used. You should use this
function with the FormGetInst() function.
Syntax FormCurr(hForm, hField)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField .............. The field handle of the field currently selected.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormGetInst
Examples See FormGetInst.

FormDestroy
Description Destroys a form, i.e. removes it from the screen. Use this function (from an event) to close a
form.
Syntax FormDestroy(hForm)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormNew
Examples
/* Display message to the operator. If after 10 seconds the operator
has not
selected OK, then destroy the form. */
hForm=FormNew("Hello",4,20,0);
 FormDestroy 367

FormPrompt(1,1,"Something bad has happened");

FormButton(5,2,"OK",0,1);
FormRead(1);

! Wait 10 seconds.
Sleep(10);
IF FormActive(hForm) THEN
! Destroy form.
FormDestroy(hForm);
END

FormEdit
Description Adds an edit field to the current form. You should call this function only after the FormNew()
function and before the FormRead() function. A user input/edit box is added to the form at the
specified column and row position. The operator can enter or edit the text in the edit box. This
text is then passed to this function as Text.
Syntax FormEdit(Col, Row, Text, Width)

Col ...................The number of the column in which the edit field will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the edit field in
column 8, enter 7.

Row..................The number of the row in which the edit field will be placed. Enter a number
from 0 (row 1) to the form height - 1. For example, to place the edit field in row
6, enter 5.

Text ..................The text in the edit field. Text initially contains the default text (if any) for the
operator to edit. When the function closes, this argument is passed back with the
operator's input.

Width ...............The width of the edit field.

Return Value The field handle if the string is successfully added, otherwise -1 is returned.
Related Functions FormNew
Examples
STRING Recipe;
FormNew("Recipe",5,30,0);
! Add edit field, default Recipe to "Jam".
Recipe="Jam";
FormEdit(1,2,Recipe,20);

! Read the form.

368 FormEdit

FormRead(0);
! Recipe will now contain the operator-entered data.

FormField
Description Adds a field control device (such as a button, check box, or edit field) to the current form. You
should call this function only after the FormNew() function and before the FormRead() function.
This function allows you to specify a control device with more detail than the other field
functions.
Syntax FormField(Col, Row, Width, Height, Type, Buffer, Text, Fn)

Col...................The number of the column in which the control will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the control in
column 8, enter 7.

Row .................The number of the row in which the control will be placed. Enter a number from
0 (row 1) to the form height - 1. For example, to place the control in row 6, enter
5.

Width ...............The width of the control device.

Height..............The height of the control device.

Type.................The type of control device:

0 ..... None
1 ..... Edit
2 ..... Edit Password
3 ..... Text
4 ..... Button
5 ..... OK button
6 ..... Cancel button
7 ..... Group box
8 ..... Radio button
9 ..... Check box

Buffer...............The output buffer for the field string. The default value of the control device is
initialised to the value of the buffer. If you specify a Radio button or Check box,
 FormField 369

you should initialise the buffer to "0" or "1". The result of the field will also be
set to "0" or "1".

Text ..................The display prompt text for a button, or the default text for an edit field (which is
then passed back with the operator's input).

Fn ....................The callback function to call when the button is selected. Set to 0 to call no
function. Note that the Fn parameter must be of type INT and the callback
function cannot contain a blocking function.

Return Value The field handle if the field is successfully added, otherwise it will return -1.
Related Functions FormNew
Examples
! Display a form with check boxes to start
! specific motors.
!
FUNCTION
SelectMotor()
INT hform;
STRING check1 = "0";
STRING check2 = "0";
STRING check3 = "0";

hform = FormNew("Selection Menu", 26, 22, 6);

FormField(16, 1, 12, 1, 9, check1, "Primary ", 0);
FormField(16, 2, 12, 1, 9, check2, "Secondary", 0);
FormField(16, 3, 12, 1, 9, check3, "backup ", 0);
FormButton( 9, 20, " &Cancel ", 0, 2);

IF FormRead(0) = 0 THEN
IF check1 = "1" THEN
StartMotor(MOTOR_1);
END
IF check2 = "1" THEN
StartMotor(MOTOR_2);
END
IF check3 = "1" THEN
StartMotor(MOTOR_3);
END
END
END
370 FormGetCurrInst

FormGetCurrInst
Description Extracts data associated with a field (set by the FormSetInst() function). You should call this
function only from within a field callback function. This function is the same as calling the
FormCurr() function and then the FormGetInst() function.
Syntax FormGetCurrInst(iData, sData)

iData ...............Integer data.

sData ...............String data.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormCurr, FormGetInst, FormSetInst
Examples
INT
FUNCTION
GetNextRec()
INT hDev;
STRING Str;

FormGetCurrInst(hDev,Str);
DevNext(hDev);
RETURN 0;
END

FormGetData
Description Gets all data associated with a form and puts it into the output string buffers. Normally the field
data is copied to the output string buffers only when the user selects the [OK] button. If you
want to use the data while the form is displayed, call this function to get the data. You should
call this function only while the form is displayed, e.g. from a field callback function.
Syntax FormGetData(hForm)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormCurr
Examples
! Field callback to save data.
FUNCTION
 FormGetData 371

Save()
INT hForm,hField;
FormCurr(hForm,hField);
FormGetData(hForm);
! Access all data.
.
.
END

FormGetInst
Description Extracts the data associated with a field (set by the FormSetInst() function). You would
normally use this function in a field callback function. It allows single callback functions to
know that the form and field are associated.
Syntax FormGetInst(hForm, hField, iData, sData)

hForm ..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField ..............The field handle of the field currently selected.

iData................Integer data.

sData ...............String data.

Return Value The data (as a string).

Related Functions FormSetInst, FormCurr, FormGetCurrInst
Examples
INT
FUNCTION
GetNextRec()
INT hDev,hForm,hField;
STRING Str;
! Get field data, e.g. the hDev value.
.
.
FormCurr(hForm,hField);
FormGetInst(hForm,hField,hDev,Str);
DevNext(hDev);
! Display new record in form.
.
.
RETURN 0;
END
372 FormGetText

FormGetText
Description Gets the current text from a form field. You should call this function only while the form is
displayed, e.g. from a field callback function.
Syntax FormGetText(hForm, hField)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField .............. The field handle of the field currently selected.

Return Value The field text (as a string).

Related Functions FormSetText
Examples
FUNCTION
Search()
INT hForm,hField;
STRING Recipe;
FormCurr(hForm,hField);
Recipe=FormGetText(hForm,hField);
! Go and find recipe.
.
.
END

FormGoto
Description Goes to a specified form. The form is displayed on top of all windows and the keyboard focus is
set to this form.
Syntax FormGoto(hForm)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormNew
Examples
FormGoto(hForm);
 FormGroupBox 373

FormGroupBox
Description Adds a group box to the current form. A group box is a form control box drawn to the specified
size. If the box contains radio buttons, they are grouped together. You should call this function
only after the FormNew() function and before the FormRead() function.
The group box is added to the form at the specified column and row position with the specified
width and height. Use the FormRadioButton() function to add the radio buttons to the box, and
call this function between each group of radio buttons.
Syntax FormGroupBox(Col, Row, Width, Height, Text)

Col ...................The number of the column in which the group box will be placed. Enter a
number from 0 (column 1) to the form width - 1. For example, to place the
group box in column 8, enter 7.

Row..................The number of the row in which the group box will be placed. Enter a number
from 0 (row 1) to the form height - 1. For example, to place the group box in
row 6, enter 5.

Width ...............The width of the group box, which should be wide enough to display your widest
item.

Height ..............The height of the group box.

Text ..................The text to display as the group box label.

Return Value The field handle if the group box is successfully added, otherwise -1 is returned.
Related Functions FormNew, FormRead, FormRadioButton
Examples
! Create a form, add to radio buttons groups and then display the form
! The operator may select one of the radio buttons from each group
FUNCTION
FnMenu()
STRING sFast, sSlow, sMedium;
STRING sNorth, sSouth, sEast, sWest;

FormNew("Select Item",40,7,1);
FormGroupBox(1 ,1, 15, 5, "Speed");
FormRadioButton(2 ,2,"Fast", sFast);
FormRadioButton(2, 3,"Medium", sMedium);
FormRadioButton(2 ,4,"Slow", sSlow);

FormGroupBox(19 ,2, 15, 6, "Direction");

FormRadioButton(20 ,2,"North", sNorth);
FormRadioButton(20, 3,"South", sSouth);
FormRadioButton(20 ,4,"East", sEast);
374 FormGroupBox

FormRadioButton(20 ,5,"West", sWest);

FormRead(0);

END

FormInput
Description Adds a prompt and edit field to the current form. You should call this function only after the
FormNew() function and before the FormRead() function. When FormRead() is called, the form
will display with the prompt and edit box. The operator's input is passed back as a string (Text).
Syntax FormInput(Col, Row, Prompt, Text, Width)

Col...................The number of the column in which the prompt will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the prompt in
column 8, enter 7.

Row .................The number of the row in which the prompt will be placed. Enter a number from
0 (row 1) to the form height - 1. For example, to place the prompt in row 6,
enter 5.

Prompt.............The prompt string.

Text.................. The output text string containing the operator's input.

Width ...............The width of the edit field.

Return Value The field handle if it is added successfully, otherwise -1 is returned.

Related Functions FormNew, FormRead
Examples
FormInput(1,2,"Recipe",Recipe,20);

FormListAddText
Description Adds a new text entry to a combo box or a list box while the form is displayed. It only adds the
text to the list - it does not select it. Use the FormListSelectText() function to select (highlight)
an entry. Call this function only when the form is displayed, e.g. from a field callback function.
Syntax FormListAddText(hForm, hField, Text)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.
 FormListAddText 375

hField ..............The field handle of the field currently selected.

Text ..................New field text.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormListSelectText, FormListDeleteText, FormSetText
Examples
/* create a form with a list */
hForm = FormNew("Ingredients", 40, 10, 1);
hField = FormListBox(2,2,20,5,sBuf);
FormAddList("Flour");
FormAddList("Water");
FormAddList("Salt");
FormAddList("Sugar");

/* Display the form */

FormRead(1);
:
:

/*Add Milk to list */

FormListAddText(hForm, hField, "Milk");
:
:

FormListBox
Description Adds a list box to the current form. The list box is a form control that allows the operator to
select from a list of items. You should call this function only after the FormNew() function and
before the FormRead() function.
The list box is added to the form at the specified column and row position with the specified
width and height. If more items are placed in the list than the list can display, a scroll bar
displays for scrolling to the hidden items.
Use the FormAddList() function to add items for display in the list box. If the form is already
displayed, you can use the FormListAddText() and FormListSelectText() functions to add (and
highlight) text in the list box.
Syntax FormListBox(Col, Row, Width, Height, sBuf, Mode)

Col ...................The number of the column in which the list box will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the list box in
column 8, enter 7.
376 FormListBox

Row ................. The number of the row in which the list box will be placed. Enter a number
from 0 (row 1) to the form height - 1. For example, to place the list box in row
6, enter 5.

Width ...............The width of the list box, in characters. Width should be wide enough to display
your widest item. Items wider than the list box are clipped.

Height..............The height of the list box, as the number of items that can be seen in the list box
without scrolling.

sBuf .................The string buffer in which to store the selected item.

Mode ...............The mode in which to create the list box:

0 ..... Sort the list box elements alphabetically.

1 ..... Place elements in list box in the order they were added.

Return Value The field handle if the list box is successfully added, otherwise -1 is returned.
Related Functions FormNew, FormRead, FormAddList, FormListAddText, FormListSelectText, FormComboBox
Examples
! Create a form, add list box and then display the form.
! The operator may select one of the items from the list.
FUNCTION
FnMenu()
STRING sBuf;

FormNew("Select Item",20,6,1);
FormListBox(2 ,2, 15, 5, sBuf, 1);
FormAddList("Item One");
FormAddList("Item two");
FormAddList("Item three");
FormRead(0);
! sBuf should contain the selected item

END

FormListDeleteText
Description Deletes an existing text entry from a combo box or a list box while the form is displayed. It only
deletes the text from the list - it does not change the selection. Call this function only when the
form is displayed, e.g. from a field callback function.
Syntax FormListDeleteText(hForm, hField, Text)
 FormListDeleteText 377

hForm ..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField ..............The field handle of the field currently selected.

Text ..................The text to delete.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormListSelectText, FormListAddText
Examples
/* create a form with a list */
hForm = FormNew("Ingredients", 40, 10, 1);
hField = FormListBox(2,2,20,5,sBuf);
FormAddList("Flour");
FormAddList("Water");
FormAddList("Salt");
FormAddList("Sugar");

/* Display the form */

FormRead(1);
:
:

/*Remove Sugar from the list */

FormListDeleteText(hForm, hField, "Sugar");
:
:

FormListSelectText
Description Selects (highlights) a text entry in a Combo box or a List box while the form is displayed. The
text to be selected must exist in the list. (Use the FormListAddText() function to add a text entry
to a list.) Call this function only when the form is displayed, e.g. from a field callback function.
Syntax FormListSelectText(hForm, hField, Text)

hForm ..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField ..............The field handle of the field currently selected.

Text ..................The text to be selected. If this text is not present in the list, then no item will be
selected (and this text will not be added).

Return Value 0 (zero) if successful, otherwise an error is returned.

378 FormListSelectText

Related Functions FormListAddText, FormSetText

Examples
/* Create a form with a list */
hForm = FormNew("Ingredients", 40, 10, 1);
hField = FormListBox(2,2,20,5,sBuf);
FormAddList("Flour");
FormAddList("Water");
FormAddList("Salt");
FormAddList("Sugar");

/* Display the form */

FormRead(1);
:
:
/*Select Flour */
FormListSelectText(hForm, hField, "Flour");
:
:

FormNew
Description Creates a new data entry form and defines its size and mode. After the form is created, you can
add fields, and then display the form.
Before you can display a form on the screen, you must call this function to set the size and mode
of the form, and then call the various form field functions, FormInput(), FormButton(),
FormEdit() etc to add user input fields to the form. To display the form on the screen (to allow
the user to enter data) call the FormRead() function.
Syntax FormNew(Title, Width, Height, Mode)

Title ................. The title of the form.

Width ...............The character width of the form (1 to 131).

Height..............The character height of the form (1 to 131).

Mode ...............The mode of the form:

0 ..... Default font and text spacing

1 ..... Small font
2 ..... Fixed pitch font
4 ..... Static text compression where the vertical spacing is reduced. This can
cause problems if buttons are too close, because the vertical spacing will be
less than the height of a button.
 FormNew 379

8 ..... Keep the form on top of the Citect window.

16... The current window cannot be changed or closed until the form is finished
or cancelled.
32... Makes a form with no caption.
128............. The form will not close if the ESC or ENTER key is pressed, unless
you specifically define at least one button on the form which acts as
an OK or Cancel button. For a form with no buttons, the ENTER
key normally closes the form - this mode disables that behaviour.
Multiple modes can be selected by adding them (for example, to use Modes 4
and 2, specify Mode 6).

Return Value The form handle if the form is created successfully, otherwise -1 is returned. The form handle
identifies the table where all data on the associated form is stored.
Related Functions FormDestroy, FormInput, FormButton, FormEdit, FormRead
Examples
FormNew("Recipe",30,5,0);
FormInput(1,1,"Recipe No",Recipe,20);
FormInput(1,2,"Amount",Amount,10);
FormRead(0);

FormNumPad
Description Provides a keypad form for the operator to add numeric values. You can customise the standard
form as a mathematical keypad, with the +, -, and / operators and the decimal point. For a time
keypad, use the AM, PM, and : (hour/minute divider) buttons. You can also include a password
edit field.
Syntax FormNumPad(Title, Input, Mode)

Title..................The title to display on the number pad form.

Input ................The existing or default value. This value is returned if the form is cancelled or
accepted without changes.

Mode................The buttons to include on the keypad form. The Mode can be a combination of
the following:

0 ..... Standard keypad

1 ..... Password edit field
2 ..... not used
380 FormNumPad

4 ..... With +/- button

8 ..... With / button
16 ... With . button
32 ... With : button
64 ... With AM, PM buttons

Return Value The string value entered by the operator. The IsError() function returns 0 (zero). If the form was
cancelled, the value of Input is returned, and the IsError() function returns error number 299.
Examples
/* Set defaults first, then four keypad forms to adjust recipe. */
Qty_Flour=FormNumPad("Add Flour", Qty_Flour, 17);
Qty_Water=FormNumPad("Add Water", Qty_Water, 17);
Qty_Salt=FormNumPad("Add Salt", Qty_Salt, 17);
Qty_Sugar=FormNumPad("Add Sugar", Qty_Sugar, 17);

FormOpenFile
Description Displays a File Open dialog box.
Syntax FormOpenFile(sTitle, sFileName, sFilter)

sTitle................ A title to display at the top of the form.

sFileName .......The name of the default file to display in the "File Name" field.

sFilter ..............A file filter list to display in the "List Files of Type" field. The file filter list has
the following format:

<File Type>|<Filter>|
where
File Type is the text that displays in the drop box, for example All Files (*.*)
Filter is the file type, for example *.CI

Return Value The name and full path of the selected file (as a string) or an empty string ("") if the Cancel
button is selected.
Related Functions FormSaveAsFile, FormSelectPrinter
Examples
// Display the Open File dialog with the following filter list:
// All Files (*.*)
 FormOpenFile 381

// Exe Files (*.EXE)

// Cicode Files (*.CI)

sFilename = FormOpenFile("Open", "*.CI", "All Files (*.*)|*.*|Exe Files

(*.EXE)|*.EXE|Cicode Files (*.CI)|*.CI|");

FormPassword
Description Adds both a password prompt and edit field to the current form. You should call this function
only after the FormNew() function and before the FormRead() function. When FormRead() is
called, the form will also display the password prompt and edit field.
The operator's input is not echoed in the field; a single asterisk (*) is displayed for each
character.
Syntax FormPassword(Col, Row, Prompt, Password, Width)

Col ...................The number of the column in which the prompt will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the prompt in
column 8, enter 7.

Row..................The number of the row in which the prompt will be placed. Enter a number from
0 (row 1) to the form height - 1. For example, to place the prompt in row 6,
enter 5.

Prompt.............The prompt string.

Password .........The password entered by the operator.

Width ...............The width of the edit field.

Return Value The field handle if it is added successfully, otherwise -1 is returned.

Related Functions FormEdit
Examples
! Add Password input.
FormPassword(1,2,"Enter Password",Password,10);

FormPosition
Description Sets the position of a form on the screen, before it is displayed. You should call this function
only after the FormNew() function and before the FormRead() function.
382 FormPosition

Syntax FormPosition(X, Y, Mode)

X ......................The x and y pixel coordinates of the form.

Y ......................The x and y pixel coordinates of the form.

Mode ...............Not used (set to 0).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormNew, FormRead
Examples
hForm = FormNew("title", 20, 5, 0);
! display form at x=100, y=50
FormPosition(100, 50, 0);

FormPrompt
Description Adds a prompt field to the current form. You should call this function only after the FormNew()
function and before the FormRead() function.
Syntax FormPrompt(Col, Row, Prompt)

Col...................The number of the column in which the prompt will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the prompt in
column 8, enter 7.

Row .................The number of the row in which the prompt will be placed. Enter a number from
0 (row 1) to the form height - 1. For example, to place the prompt in row 6,
enter 5.

Prompt.............The prompt string.

Return Value The field handle if it is added successfully, otherwise -1 is returned.

Related Functions FormNew, FormRead
Examples
FormPrompt(1,2,"Enter Recipe");
 FormRadioButton 383

FormRadioButton
Description Adds a radio button to the current form, allowing the operator to make a selection from a
multiple choice list. You should call this function only after the FormNew() function and before
the FormRead() function.
The radio button is added to the form at the specified column and row position. The width of the
button will be sized to suit the text.
By default, all radio buttons are placed into the one group. If you require separate groups, use
this function in conjunction with the FormGroupBox() function.
Syntax FormRadioButton(Col, Row, sText, sBuf)

Col ...................The number of the column in which the button will be placed. Enter a number
from 0 (column 1) to the form width - 1. For example, to place the button in
column 8, enter 7.

Row..................The number of the row in which the button will be placed. Enter a number from
0 (row 1) to the form height - 1. For example, to place the button in row 6, enter
5.

sText ................The text associated with the radio button.

sBuf..................The string buffer in which to put the state of the radio button. You should
initialise this buffer to the state of the button. When the form returns, this buffer
will contain either '1' or '0' if the radio button is checked.

Return Value The field handle if the radio button is successfully added, otherwise -1 is returned.
Related Functions FormNew, FormRead, FormGroupBox, FormCheckBox
Examples
! Create a form, add radio buttons and then display the form.
! The operator may only select one radio button, either Fast, Medium or
Slow
FUNCTION
FnMenu()
STRING sFast, sSlow, sMedium;
sFast = "1";
sMedium = "0";
sSlow = "0";

FormNew("Speed",20,6,1);
FormRadioButton(2 ,2,"Fast", sFast);
FormRadioButton(2, 3,"Medium", sMedium);
FormRadioButton(2 ,4,"Slow", sSlow);
FormRead(0);
384 FormRadioButton

If sFast = "1" THEN

! do fast stuff
ELSE
IF sMedium = "1" THEN
! do Medium stuff
ELSE
IF sSlow = "1" THEN
! do slow stuff
END
END
END
END

FormRead
Description Displays the current form (created with the FormNew() function), with all the fields that were
added (with the form field functions).
You can display the form and wait for the user to finish entering data by setting the Mode to 0.
This mode is the most commonly used, with [OK] and [Cancel] buttons to either save or discard
operator entries and to close the form.
To display the form and return before the user has finished, use Mode 1. This mode is used to
animate the data on the form or to perform more complex operations.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax FormRead(Mode)

Mode ...............Mode of the form:

0 ..... Wait for the user.

1 ..... Do not wait for the user.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormNew
Examples
! Display the form and wait for the user.
FormRead(0);

! Display the form and do not wait for the user.

FormRead(1);
! While the form is displayed, update the
time every second.
WHILE FormActive(hForm) DO
 FormRead 385

FormSetText(hForm,hField,Time());
Sleep(1);
END

FormRead; FmtClose(hFmt)
Description Closes a format template. After it is closed, the template cannot be used. Closing the template
releases system memory.
Syntax FormRead()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FmtOpen
Examples
FmtClose(hFmt);

FormSaveAsFile
Description Displays a File Save As dialog box.
Syntax FormSaveAsFile(sTitle, sFileName, sFilter, sDefExt)

sTitle ................A title to display at the top of the form.

sFileName........The name of the default file to display in the "File Name" field.

sFilter ..............A file filter list to display in the "List Files of Type" field. The file filter list has
the following format:

<File Type>|<Filter>|
where
File Type is the text that displays in the drop box, for example All Files (*.*)
Filter is the file type, for example *.CI

sDefExt ............The file extension that will be used as a default when you use the
FormSaveAsFile() function. If you do not specify a default extension, files will
be saved without an extension.

Return Value The name and full path of the selected file (as a string) or an empty string ("") if the Cancel
button is selected.
386 FormSaveAsFile

Related Functions FormOpenFile, FormSelectPrinter

Examples
// Display the SaveAs dialog with the following filter list:
// All Files (*.*)
// Exe Files (*.EXE)
// Cicode Files (*.CI)

sFilename = FormSaveAsFile("Save As", "Alarms", "All Files (*.*)|*.*|Exe

Files (*.EXE)|*.EXE|Cicode Files (*.CI)|*.CI|", "ci");

FormSelectPrinter
Description Displays the Select Printer dialog box.
Syntax FormSelectPrinter()

Return Value The name of the selected printer (as a string) or an empty string ("") if the Cancel button is
selected.
Related Functions FormOpenFile, FormSaveAsFile,
Examples
// Display the Select Printer dialog
sPrinter = FormSelectPrinter();

FormSetData
Description Sets all the edit data from the string buffers into the form. You should call this function only
while the form is active.
Syntax FormSetData(hForm)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormGetData
Examples
INT
FUNCTION
MyNextRec()
INT hForm,hField;
 FormSetData 387

FormCurr(hForm,hField);
FormSetData(hForm);
RETURN 0;
END

FormSetInst
Description Associates an integer and string value with each field on a form. This data could then be used by
a callback function. You can use a single callback function for all fields, and use the data to
perform different operations for each field.
Syntax FormSetInst(hForm, hField, iData, sData)

hForm ..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField ..............The field handle of the field currently selected.

iData................Integer data.

sData ...............String data.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormGetInst
Examples
! Open recipe database.
hDev=DevOpen("Recipe", 0);
hForm=FormNew("Recipe",20,5,0);
hField=FormButton(5,2,"Next",GetNextRec,0);
FormSetInst(hForm,hField,hDev,"");

/* The device handle hDev is put into the next button, so when the
button is selected it can get hDev and get the next record. */

FormSetText
Description Sets new field text on a field. This function allows you to change field text while the form is
displayed. Call this function only when the form is displayed, e.g. from a field callback function.
If you are using this function on a Combo box or a List box, it will select the text from the
Combo box or List box list. If no text exists in the Combo box or List box list, the function will
add it.
388 FormSetText

Syntax FormSetText(hForm, hField, Text)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

hField .............. The field handle of the field currently selected.

Text.................. New field text.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FormCurr, FormListSelectText, FormListAddText
Examples
/* Create a form with a field */
hForm = FormNew("Ingredients", 40, 10, 1);
hField = FormPrompt(2,2,"Motor1:");

/* Display the form*/

FormRead(1);
:
:
/* Change the text in the field */
FormSetText(hForm, hField, "Pump1:");
:

FormWndHnd
Description Gets the window handle for the given form. The window handle may be used by 'C' programs
and Citect Wnd... functions. You should call this function only after the FormNew() function
and before the FormRead() function.
The window handle is not the same as the Citect window number and cannot be used with
functions that expect the Citect window number (the Win... functions).
Syntax FormWndHnd(hForm)

hForm..............The form handle, returned from the FormNew() function. The form handle
identifies the table where all data on the associated form is stored.

Return Value The window handle if successful, otherwise a 0 is returned.

Related Functions FormNew, FormRead, WndFind
Examples
/* Create a form with a field */
hForm = FormNew("Ingredients", 40, 10, 1);
 FormWndHnd 389

hField = FormPrompt(2,2,"Motor1:");

/* Get the form's window number for future reference */

hWnd = FormWndHnd(hForm);

/* Display the form*/

FTPClose
Description Closes an FTP session.
Syntax FTPClose(hndFTP)

hndFTP............The handle of a valid FTP session, as returned by FTPOpen().

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FTPOpen
Examples

INT hFtp;
hFtp = FtpOpen("", "", "");
.
.
.
.
FtpClose(hFtp);

FTPFileCopy
Description Copies a file from the FTP server to the Internet Display Client. Before calling this function,
you must call FtpOpen().
Syntax FTPFileCopy(hndFTP, sSrcPath, sDestPath)

hndFTP............The handle of a valid FTP session, as returned by FTPOpen().

sSrcPath ..........The file name and path of the file to be copied from the FTP Server to the
Internet Display Client. This can be any FTP server.

sDestPath ........The destination of the copied file (including the name of the file).

Return Value 0 (zero) if successful, otherwise an error is returned.

390 FTPFileCopy

NOTE: The [Internet]ZipFiles parameter does not apply to files copied to the Internet Display Client using this
function.

Related Functions FTPOpen, FTPFileFind

FTPFileFind
Description Finds a file on the FTP server that matches a specified search criteria. Before you can call this
function, you must call FTPOpen().
To find a list of files, you must first call this function twice - once to find the first file, then again
with an empty path to find the remaining files. After the last file is found, an empty string is
returned.
Syntax FTPFileFind(hndFTP, sPath)

hndFTP ........... The handle of a valid FTP session, as returned by FTPOpen().

sPath ...............The path you wish to search for the desired file. Do not use path substitution
here.

Return Value The full path and filename. If no files are found, an empty string is returned.
Related Functions FtpFileCopy, FTPOpen,
Examples

INT hFtp;
STRING sFindPath;
STRING sPath;

sFindPath = "\User\Example\*.RDB";
hFtp = FtpOpen("", "", "");
sPath = FtpFileFind(hFtp, sFindPath);
WHILE StrLength(sPath) > +0 DO
sPath = FtpFileFind(hFtp, "");
END
FtpClose(hFtp);
 FTPOpen 391

FTPOpen
Description Connects to an FTP server.
Syntax FTPOpen(sIPAddress, sUsername, sPassword)

sIPAddress.......The TCP/IP address of the FTP server you wish to connect to (e.g. 10.5.6.7 or
plant.yourdoman.com). If you do not specify an IP address, the Citect FTP
server running on the Internet Server you are connected to will be used.

sUsername .......The FTP login username. If you omit both the username and IP address, the
Citect FTP password will be used. If you omit just the username, an anonymous
logon will occur.

sPassword........The FTP server password. If you wish to log on anonymously or you wish to log
on to the Citect FTP server, do not specify a password, here.

Return Value A handle to the FTP server otherwise -1 if an error occurs (e.g. the server cannot be found).
Related Functions FTPClose

FullName
Description Gets the full name of the user who is currently logged-in to the system.
Syntax FullName()

Return Value The user name (as a string).

Related Functions Name, UserInfo
Examples
/* Display the full name of the current user at AN20. */
DspText(20, 0, FullName());

FuzzyClose
Description Frees all memory and information for the specified instance. After the fuzzy instance is closed,
the handle given in the hFuzzy parameter is no longer valid.
Syntax FuzzyClose(hFuzzy)

hFuzzy..............The fuzzy instance handle (and integer greater than 0).

392 FuzzyClose

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FuzzyOpen.
Examples
See the example for FuzzyOpen().

FuzzyGetCodeValue
Description Gets a value for the specified input of the specified instance.
Syntax FuzzyGetCodeValue(hFuzzy, iIOIndex, NoHitFlag)

hFuzzy ............. The fuzzy instance handle (and integer greater than 0).

iIOIndex ..........Specifies the variable to receive the value. The I/O-Indices start with 0 and
increment by 1 for each variable. To find the correct index for a specific
variable, the variables must be sorted in alpha-numerical order, first the inputs
and then the outputs.

NoHitFlag .......Variable to receive the new value of the No-hit-flag. The No-hit-flag is TRUE if
no rule was active for the variable specified by iIOIndex, otherwise it is FALSE.
This must be a Cicode variable of INT type - it cannot be a constant or PLC
variable tag.

Return Value The code value if the function was successful. Use IsError()to find the error number if the
function fails.
Related Functions FuzzyOpen, FuzzySetCodeValue.
Examples
See the example for FuzzyOpen().

FuzzyGetShellValue
Description Gets a value for the specified input of the specified instance. The variables in the instance must
have the data type REAL (floating point values).
Syntax FuzzyGetShellValue(hFuzzy, iIOIndex, NoHitFlag)

hFuzzy ............. The fuzzy instance handle (and integer greater than 0).

iIOIndex ..........Specifies the variable to receive the value. The I/O-Indices start with 0 and
increment by 1 for each variable. To find the correct index for a specific
 FuzzyGetShellValue 393

variable, the variables must be sorted in alpha-numerical order, first the inputs
and then the outputs.

NoHitFlag........Variable to receive the new value of the No-hit-flag. The No-hit-flag is TRUE if
no rule was active for the variable specified by iIOIndex, otherwise it is FALSE.
This must be a Cicode variable of INT type - it cannot be a constant or PLC
variable tag.

Return Value The shell value if the function was successful. Use IsError()to find the error number if the
function fails.
Related Functions FuzzyOpen, FuzzySetShellValue.
Examples
See the example for FuzzyOpen().

FuzzyOpen
Description This function loads a *.FTR file, allocates memory and creates a handle for this fuzzy instance.
To use the FuzzyTech functions you must be a registered user of one or more of the following
fuzzyTech products: fuzzyTECH Online Edition, fuzzyTECH Precompiler Edition, or
fuzzyTECH for Business PlusC. And you must only use fuzzyTECH to generate the *.FTR file
for FTRUN.
The application must call the FuzzyClose function to delete each fuzzy instance handle returned
by the FuzzyOpen function.
Syntax FuzzyOpen(sFile)

sFile.................Specifies the filename of the .FTR file to load.

Return Value The handle to the fuzzy instance, or -1 if the function fails. Use IsError()to find the error
number.
Related Functions FuzzyClose, FuzzyGetShellValue, FuzzySetShellValue, FuzzyGetCodeValue,
FuzzySetCodeValue, FuzzyTrace.
Examples
INT hFuzzy;
INT NoHitFlag;
INT Status;
REAL MemOutput;

// open the Fuzzy Tech runtime instance

hFuzzy = FuzzyOpen("C:\CITECT\BIN\TRAFFIC.FTR");
Status = IsError();
IF hFuzzy <> -1 THEN
394 FuzzyOpen

MemOutput = PLCOutput;
WHILE Status = 0 DO
FuzzySetShellValue(hFuzzy, 0, 42.0);
FuzzySetShellValue(hFuzzy, 1, 3.14150);
MemOutput = FuzzyGetShellValue(hFuzzy, 2, NoHitFlag);
Status = IsError();
// Only write to PLC if output changes.
// This reduces load on PLC communication.
IF MemOutput <> PLCOutput THEN
PLCOutput = MemOutput;
END
SleepMS(500);
END
FuzzyClose(hFuzzy);
END

FuzzySetCodeValue
Description Sets a value for the specified input of the specified instance.
Syntax FuzzySetCodeValue(hFuzzy, iIOIndex, iCodeValue)

hFuzzy ............. The fuzzy instance handle (and integer greater than 0).

iIOIndex ..........Specifies the variable to receive the value. The I/O-Indices start with 0 and
increment by 1 for each variable. To find the correct index for a specific
variable, the variables must be sorted in alpha-numerical order, first the inputs
and then the outputs.

iCodeValue...... The value to be copied to the variable specified by iIOIndex.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FuzzyOpen, FuzzyGetCodeValue.
Examples
See the example for FuzzyOpen().

FuzzySetShellValue
Description Sets a value for the specified input of the specified instance.
Syntax FuzzySetShellValue(hFuzzy, iIOIndex, rShellValue)

hFuzzy ............. The fuzzy instance handle (and integer greater than 0).
 FuzzySetShellValue 395

iIOIndex...........Specifies the variable to receive the value. The I/O-Indices start with 0 and
increment by 1 for each variable. To find the correct index for a specific
variable, the variables must be sorted in alpha-numerical order, first the inputs
and then the outputs.

rShellValue ......The value to be copied to the variable specified by iIOIndex.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FuzzyOpen, FuzzyGetShellValue.
Examples
See the example for FuzzyOpen().

FuzzyTrace
Description Controls the trace process (starting and stopping) of the specified instance.
Syntax FuzzyTrace(hFuzzy, TraceOn)

hFuzzy..............The fuzzy instance handle (and integer greater than 0).

TraceOn...........Specifies whether to start or to stop a trace process for the Fuzzy instance
specified by hFuzzy. If this parameter is TRUE (1), the trace process is started.
If this parameter is FALSE (0), the trace process is stopped.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions FuzzyOpen.
Examples
See the example for FuzzyOpen().

GetArea
Description Gets the current logged-in areas.
Syntax GetArea()

Return Value The login area groups as an integer that represents a group handle. If this group is modified, the
actual login areas do not change.
Related Functions SetArea
Examples
396 GetArea

! If the current areas are 1, 5 and 20:

hGrp=GetArea();
Str=GrpToStr(hGrp);
! sets Str to "1,5,20".

GetBlueValue
Description Returns the Blue component of a packed RGB colour.
Syntax GetBlueValue(nPackedRGB)

nPackedRGB ...The packed RGB colour.

Return Value The red value (0-255) - if successful, otherwise an error is returned.
Related Functions GetRedValue, GetGreenValue

GetEnv
Description Gets a DOS environment variable.
Syntax GetEnv(sName)

sName.............. The name of the environment variable.

Return Value The DOS environment variable (as a string).

Examples
/* Get the current DOS path. */
sPath = GetEnv("Path");

GetEvent
Description Gets the function handle of the existing callback event handler. You can use this function handle
in the ChainEvent() function to chain call the existing event function, or in the SetEvent()
function to restore the event handler.
Syntax GetEvent(Type)

Type.................The type of event:

0 .... The mouse has moved. When the mouse moves the callback function is
called. The return value must be 0.
 GetEvent 397

1 .... A key has been pressed. When the user presses a key, the callback function
is called after Citect checks for hot keys. If the return value is 0, Citect
checks for key sequences. If the return value is not 0, Citect assumes that
you will process the key and does not check the key sequence. It is up to
you to remove the key from the key command line.

NOTE:....... If you are using a right mouse button click as an event, you should
read about the ButtonOnlyLeftClick parameter.
2 .... Error event. This event is called if an error occurs in Cicode, so you can
write a single error function to check for your errors. If the return value is
0, Citect continues to process the error and generates a hardware error - it
may then halt the Cicode task. If the return value is not 0, Citect assumes
that you will process the error, and continues the Cicode without generating
a hardware error.
3 ..... Page user communication error. A communication error has occurred in
the data required for this page. If the return value is 0 (zero), Citect still
animates the page. If the return value is not zero, Citect does not update the
page.
4 ..... Page user open. A new page is being opened. This event allows you to
define a single function that is called when all pages are opened. The return
value must be 0.
5 ..... Page user close. The current page is being closed. This event allows you to
define a single function that is called when all pages are closed. The return
value must be 0.
6 ..... Page user always. The page is active. This event allows you to define a
single function that is called when all pages are active. The return value
must be 0.
7 ..... Page communication error. A communication error has occurred in the
data required for this page. Reserved for use by Citect.
8 ..... Page open. This event is called each time a page is opened. Reserved for
use by Citect.
9 ..... Page close. This event is called each time a page is closed. Reserved for
use by Citect.
10.... Page always. This event is called while a page is active. Reserved for use
by Citect.
11..17 Undefined.
18.... Report start. The report server is about to start a new report. This event is
called on the report server. The return value must be 0.
19.... Device history. A device history has just completed. The return value must
be 0.
398 GetEvent

20 ... Login. A user has just logged in.

21 ... Logout. A user has just logged out.
22 ... Trend needs repainting. This event is called each time Citect re-animates a
real-time trend or scrolls an historical trend. You should use this event to
add additional animation to a trend, because Citect deletes all existing
animation when a trend is re-drawn. (For example, if you want to display
extra markers, you must use this event.)
23 ... Hardware error occurred.
24 ... Keyboard cursor moved. This event is called each time the keyboard
command cursor moves. The cursor can be moved by the cursor keys, the
mouse, or the Cicode function KeySetCursor(). Note that you can find
where the keyboard command cursor is located by calling the function
KeyGetCursor().
25 ... Network shutdown. A Shutdown network command has been issued.
26 ... Runtime system shutdown and restart. (Required because of configuration
changes.)
27 ... Event. An event has occurred.
28 ... Accumulator. An accumulator has logged a value.
29 ... Slider. A slider has been selected.
30 ... Slider. A slider has moved.
31 ... Slider. A slider has been released (i.e. stopped moving).

NOTE: .......1) While responding to slider events 29, 30, and 31, you can set any
variables but you cannot call functions that cause immediate changes
to animations on the page (e.g. DspText() and DspSym()).
2) Types 29, 30, & 31 relate only to V3.xx and V4.xx animations,
and will be superseded in future releases.
32 ... Shutdown. Citect is being shutdown.
33... 127 Reserved for future Citect use.
128... 256 ...User defined events. These events are for your own use.

Return Value The function handle of the existing callback event handler, or -1 if there are no event handlers.
Related Functions OnEvent, CallEvent, ChainEvent, SetEvent
Examples
! Get existing event handler.
hFn=GetEvent(0);
! Trap mouse movements.
OnEvent(0,MouseFn);
 GetEvent 399

.
.
! Restore old event handler.
SetEvent(0,hFn);

INT
FUNCTION
MouseFn()
.
.
! Chain call old event handler.
RETURN ChainEvent(hFn);
END

GetGreenValue
Description Returns the green component of a packed RGB colour.
Syntax GetGreenValue(nPackedRGB)

nPackedRGB ...The packed RGB colour.

Return Value The red value (0-255) - if successful, otherwise an error is returned.
Related Functions GetRedValue, GetBlueValue

GetPriv
Description Checks if the current user has a privilege for a specified area. With this function, you can write
your own Cicode functions to control user access to the system.
Syntax GetPriv(Priv, Area)

Priv ..................The privilege level (1..8).

Area .................The area of privilege (0..255).

Return Value Returns 1 if the user has the specified privilege in the area, or 0 (zero) if the user does not have
the privilege.
Related Functions SetArea
Examples
/* User must have privilege 2, or cannot do operation. */
IF GetPriv(2, 0) THEN
400 GetPriv

! Do operation here
ELSE
Prompt("No privilege for command");
END

GetRedValue
Description Returns the red component of a packed RGB colour.
Syntax GetRedValue(nPackedRGB)

nPackedRGB ...The packed RGB colour.

Return Value The red value (0-255) - if successful, otherwise an error is returned.
Related Functions GetGreenValue, GetBlueValue

GrpClose
Description Closes a group. The group is destroyed and the group handle becomes invalid. You should
close a group when it is not in use, to release the associated memory. Citect closes all groups on
shutdown.
Syntax GrpClose(hGrp)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen
Examples
hGrp=GrpOpen("MyGrp",1);
.
.
GrpClose(hGrp);

GrpDelete
Description Deletes a single element or all elements from a group. You can also delete another group from
within the group.
 GrpDelete 401

Syntax GrpDelete(hGrp, Value)

hGrp ................The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Value................The element to delete from the group, from 0 to 16375.

Set Value to -1 to delete all elements from the group.

Set Value to a group handle to delete another group from this group.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpInsert, GrpOpen
Examples
! Delete 10 and 14 from a group.
GrpDelete(hGrp,10);
GrpDelete(hGrp,14);

GrpFirst
Description Gets the value of the first element in a group. The first element in the group is the element with
the lowest value. You can follow this function with a GrpNext() call, to get the value of all the
elements in a group.
Syntax GrpFirst(hGrp)

hGrp ................The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Return Value The value of the first element in a group or -1 if the group is empty.
Related Functions GrpOpen, GrpNext
Examples
Value=GrpFirst(hGrp);
IF Value<>-1 THEN
Prompt("First value is "+Value:###);
END
402 GrpIn

GrpIn
Description Determines if an element is in a group.
Syntax GrpIn(hGrp, Value)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Value ...............The element to locate, from 0 to 16375.

Set Value to a group handle to check if another group exists in the group.

Return Value 1 if the element is in the group, otherwise 0 is returned.

Related Functions GrpOpen, GrpInsert, GrpDelete
Examples
IF GrpIn(hGrp,10) THEN
Prompt("Area 10 in this group");
END

GrpInsert
Description Adds an element (or another group) to a group.
Syntax GrpInsert(hGrp, Value)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Value ...............The element to add to the group, from 0 to 16375.

Set Value to -1 to add all elements (0 to 16375) to the group.

Set Value to a group handle to insert another group into the group.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen, GrpDelete, GrpIn
Examples
! Add 10 and 14 to a group.
GrpInsert(hGrp,10);
GrpInsert(hGrp,14);
 GrpMath 403

GrpMath
Description Performs mathematical operations on two groups, and stores the result in another group. You
can add the two groups, subtract one from the other, or perform Boolean AND, NOT, and XOR
operations on the two groups.
Syntax GrpMath(hResult, hOne, hTwo, Type)

hResult.............The group number where the result is placed.

hOne ................hOne The number of the first group used in the mathematical operation.

hTwo......... The number of the second group used in the mathematical operation.

hTwo ................hOne The number of the first group used in the mathematical operation.

hTwo......... The number of the second group used in the mathematical operation.

Type .................Type of mathematical operation:

0 ..... Add groups one and two.

1 ..... Subtract group two from group one.
2 ..... AND groups one and two.
3 ..... NOT groups one and two.
4 ..... XOR groups one and two.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen
Examples
hOne=GrpOpen("Plantwide",0);
hTwo=GrpOpen("Section1",0);
hResult=GrpOpen("Result",0);

! Subtract Section1 from Plantwide and place in Result.

GrpMath(hResult,hOne,hTwo,1);
404 GrpName

GrpName
Description Gets the name of a group from a group handle.
Syntax GrpName(hGrp)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Return Value The name of the group (as a string).

Related Functions GrpOpen
Examples
! Get the current group name.
sName=GrpName(hGrp);

GrpNext
Description Gets the value of the next element in a group. You can get the value of all the elements in a
group. Call the GrpFirst() function to get the value of the first element, and then call this
function in a loop.
Syntax GrpNext(hGrp, Value)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Value ...............The value returned from GrpFirst() or the latest GrpNext() call.

Return Value The value of the next element in a group, or -1 if the end of the group has been found.
Related Functions GrpFirst
Examples
! Count all values in a group.
Count=0;
Value=GrpFirst(hGrp);
WHILE Value<>-1 DO
Count=Count+1;
Value=GrpNext(hGrp,Value);
END
Prompt("Number of values in group is "+Count:###);
 GrpOpen 405

GrpOpen
Description Creates a group and returns a group handle, or gets the group handle of an existing group. After
you open a group, you can use the group number in functions that use groups, e.g. SetArea() and
AlarmSetInfo(). You can open a group that is specified in the Groups database. You can also
create groups at runtime.
When you open a group that is defined in the database, a copy of the group is made - the original
group is not used. You can therefore change the values in the group without affecting other
facilities that use this group.
Syntax GrpOpen(Name, Mode)

Name................The name of the group to open.

Mode................The mode of the open:

0 ..... Open an existing group

1 ..... Create a new group
2 ..... Attempts to open an existing group. If the group does not exist, it will
create it.

Return Value The group handle , or -1 if the group cannot be created or opened. The group handle identifies
the table where all data on the associated group is stored.
Related Functions GrpClose
Examples
! Open Plantwide group defined in the database.
hGrp=GrpOpen("Plantwide",0);

! Set current user area to Plantwide.

SetArea(hGrp);
GrpClose(hGrp);

! Set area to 1...10, 20 and 25 by creating a new group.

hGrp=GrpOpen("MyGrp",1);
StrToGrp(hGrp,"1..10,20,25");
SetArea(hGrp);
GrpClose(hGrp);
406 GrpToStr

GrpToStr
Description Converts a group into a string of values separated by " , " and " .. ". You can then display the
group on the screen or in a report.
Syntax GrpToStr(hGrp)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Return Value The group (as a string).

Related Functions GrpOpen, StrToGrp
Examples
! Display current areas.
hGrp=GetArea();
Str=GrpToStr(hGrp);
DspStr(21,"WhiteFont",Str);

Halt
Description Stops the execution of the current Cicode task and returns to Citect. This function does not
affect any other Cicode tasks that are running.
Use this function to stop execution in nested function calls. When Halt() is called, Cicode
returns to Citect and does not execute any return function calls.
Syntax Halt()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Assert, TaskKill
Examples
INT
FUNCTION
MyFunc(INT Arg)
IF Arg<0 THEN
Prompt("Invalid Arg");
Halt();
END
.
.
END
 HexToStr 407

HexToStr
Description Converts a number into a hexadecimal string. The string is the width specified (padded with
zeros).
Syntax HexToStr(Number, Width)

Number ............The number to convert.

Width ...............The width of the string.

Return Value A string containing the converted number.

Related Functions StrToHex, IntToStr
Examples
Variable=HexToStr(123, 4);
! Sets Variable to "007B".
Variable = HexToStr(0x12ABFE, 8);
! Sets Variable to "0012ABFE"

HighByte
Description Gets the high-order byte of a two-byte integer.
Syntax HighByte(TwoByteInteger)

TwoByteInteger A two-byte integer.

Return Value The high-order byte (i.e. | X | - |)

Related Functions LowByte, HighWord, LowWord
Examples
Variable=HighByte(0x5678);
! Sets Variable to 0x56.

HighWord
Description Gets the high-order word of a four-byte integer.
Syntax HighWord(FourByteInteger)

FourByteInteger A four-byte integer.

408 HighWord

Return Value The high-order word (i.e. | X | X | - | - |)

Related Functions LowWord, HighByte, LowByte
Examples
Variable=HighWord(0x12345678);
! Sets Variable to 0x1234.

InfoForm
Description Displays graphics object information for the object under the mouse pointer. If there is no object
directly under the mouse pointer, it displays information for the nearest object. Each tag
associated with the object is displayed, along with its raw and engineering values and a button
that displays all the details from the Variable Tags form. The function also displays the Cicode
expression, with any result that the expression has generated.
This function only supports the display of simple Cicode expressions.
Syntax InfoForm(Mode)

Mode ...............For security purposes, the "Write" button on the information form displayed by
this function can be disabled.

0 ..... The "Write" button on the displayed information form will be available and
will function normally.
1 ..... The "Write" button will not be shown.
If you do not enter a mode, the default mode is 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions InfoFormAn
Examples

System Keyboard
Key Sequence AnHelp

Command InfoForm();

Comment Display graphics object help for the AN

closest to the cursor
 InfoFormAn 409

InfoFormAn
Description Displays graphics object information for a specified AN. This function displays each tag
associated with the object, along with its raw and engineering values and a button that displays
all the details from the Variable Tags form. The function also displays the Cicode expression,
with any result that the expression has generated.
Syntax InfoFormAn(AN, Mode)

AN....................The AN of the graphics object for which information is displayed.

Mode................For security purposes, the "Write" button on the information form displayed by
this function can be disabled.

0 ..... The "Write" button on the displayed information form will be available and
will function normally.
1 ..... The "Write" button will not be shown.
If you do not enter a mode, the default mode is 0.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions InfoForm
Examples

System Keyboard
Key Sequence ### AnHelp

Command InfoFormAn(Arg1);

Comment Display graphics object help for a

specified AN

Input
Description Displays a dialog box in which an operator can input a single value. The dialog box has a title, a
prompt, and a single edit field. For multiple inputs, use the Form functions.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax Input(Title, Prompt, Default)
410 Input

Title ................. The title of the input box.

Prompt.............The prompt text.

Default.............The default text that the operator can edit or replace.

Return Value The edit field entry (as a string). If the user presses the Cancel button, an empty string is
returned and the IsError() function returns the error code 299.
Related Functions Message, FormNew
Examples
/* Shut down Citect if the user inputs "Yes". */

STRING sStr;
sStr=Input("Shutdown","Do you wish to shutdown?","Yes");

IF sStr="Yes" THEN
Shutdown();
END

IntToReal
Description Converts an integer into a real (floating point) number.
Syntax IntToReal(Number)

Number............ The integer to convert.

Return Value The real number.

Related Functions RealToStr, StrToInt
Examples
! Sets Variable to 45.0
Variable=IntToReal(45);
! Sets Variable to -45.0
Variable=IntToReal(-45);
 IntToStr 411

IntToStr
Description Converts a number into a string.
Syntax IntToStr(Number)

Number ............The number to convert.

Return Value A string containing the converted number.

Related Functions StrFormat
Examples
Variable=IntToStr(5);
! Sets Variable to "5".

IODeviceControl
Description Provides control of individual I/O Devices. You might need to call this function several times.
If you use incompatible values for the various options of this function, you may get
unpredictable results.
For remote I/O Devices, you should only call this function on the I/O Server on which the I/O Device is
defined.
Syntax IODeviceControl(IODevice, Type, Data)

IODevice..........The number or name of the I/O Device. If you call this function from an I/O
server, you can use the I/O Device name. If you call this function from a client,
you may use either the I/O Device number or name. To specify all I/O Devices,

*
use " " (asterisk) or -1.

Type .................The type of control action:

0 ..... Disable requests to the I/O Device from this client. All attempts to read and
write from this client are ignored. This command does not affect the
physical I/O Device on the I/O server - other clients can still communicate
with the I/O Device.
1 ..... Disable the I/O Device on the I/O server. All attempts to read and write
from the I/O Device are ignored. (If another I/O Device is configured as a
standby I/O server, Citect switches communications to that I/O Device.)
The I/O server does not attempt to communicate with the I/O Device until it
is re-enabled. When the I/O Device is re-enabled, the I/O server attempts to
re-establish communication immediately. Mode 1 can only be called by the
I/O Server which is associated with this device.
412 IODeviceControl

2 ..... Attach the I/O Device specified in Data to the transparent I/O Device
specified in IODevice. The attached I/O Device data will apply only to
graphics object information on the next page that is displayed.
3 ..... Attach the I/O Device specified in Data to the transparent I/O Device
specified in IODevice. The attached I/O Device data will apply to the
entire system.
4 ..... All the data in the associated I/O Device cache is flushed. This allows
flushing of all the data from the I/O Device without waiting for the aging
time. This is useful when you have very long cache time and you want to
force a read from the I/O Device.
....... You can only flush the cache of the I/O Device on the computer you called
this function from. If called from a client, it will not flush the cache on the
I/O Server. The Data value is ignored with this mode.
5 ..... (For scheduled and remote I/O Devices) The I/O Device is added to the
bottom of the list of I/O Devices to be contacted. I/O Devices already in
the list (already waiting to be contacted) are given priority over this I/O
Device.
6 ..... (For scheduled and remote I/O Devices) The I/O Device is added to the top
of the list of I/O Devices to be contacted - it is given high priority. If there
are already I/O Devices at the top of the list with high priority, then this I/O
Device will be added to the list after them (i.e. it will be contacted after
them). For diallable remote I/O Devices, if the modem is already in use -
connected to another I/O Device - this I/O Device will not be dialled until
that connection has been terminated.
7 ..... (For scheduled and remote I/O Devices) The I/O Device is added to the top
of the list of I/O Devices to be contacted, and it is given top priority. For
diallable remote I/O Devices, if the modem is currently connected to
another I/O Device, the connection will be cancelled, and the top priority
I/O Device will be dialled. It will also stay connected until manually
disconnected with another call to IODeviceControl().
8 ..... (For scheduled and remote I/O Devices) Disconnect an I/O Device.
Current requests will be completed before the I/O Device is disconnected.
9 ..... (For scheduled I/O Devices) The communication schedule for the I/O
Device is disabled. This prevents the I/O Device from being contacted
when its scheduled dial-time occurs.
10 ... (For scheduled I/O Devices) Puts the I/O Device into Write On Request
mode. i.e., as soon as a write request is made, the I/O Device will be added
to the list of I/O Devices to be contacted. It is given priority over existing
read requests, but not over existing write requests.

WARNING: In this situation, it is important to recognise that there will be a

slight delay while the I/O Device is contacted. Do not mistake this
 IODeviceControl 413

pause for inactivity (for example, do not continually execute a

command during this delay).
11.... Change the I/O Device cache timeout. If the I/O Server is restarted, the
cache timeout will return to its original value. (For scheduled I/O Devices,
this value can be checked using the Kernel Page Unit command. For all
other I/O Devices, this value is configured in the Cache Time field at the
I/O Devices Properties form.)
12.... The time of day at which to add the I/O Device to the list of I/O Devices to
be contacted. Set the time in Data in seconds from midnight (e.g. specify 6
p.m. as 18 * 60 * 60). Use Type 12 to specify a one-off communication.
13.... The communication period (the time between successive communication
attempts). The value you specify represents different periods, depending on
what type of schedule you are using (i.e. daily, weekly, monthly, or yearly.
This is set using Type 15.). You can choose to specify the communication
period either in seconds from midnight, day of week (0 to 6, Sunday = 0),
month (1 to 12), or year. Enter the value in Data. For example, if your
schedule is weekly, and you set Data = 3, you are specifying each
Wednesday. If your schedule is monthly, Data = 3 indicates March. For
daily communication, set the period in Data in seconds from midnight; e.g.
set Data to 6 * 60 * 60 to contact the I/O Device every 6 hours.
14.... The time at which the I/O Server will first attempt to communicate with the
I/O Device. Set the time in Data in seconds from midnight, e.g. to
synchronise at 10a.m., set Data to 10 * 60 * 60.
15.... Type of schedule. Set Data to one of the following:
1 ..... Daily
2 ..... Weekly
3 ..... Monthly
4 ..... Yearly
16.... Read all tags from the I/O Device. Data is unused - set it to 0 (zero).

Data.................Data for the control operation*:

1 ..... Disable the I/O Device (Disable Write On Request mode for Type 10)
0 ..... Enable the I/O Device (Enable Write On Request mode for Type 10)
....... - or -
the I/O Device name (for Type 2 or 3).
*For Type 5-8, Data is ignored; enter 0 (zero).

Return Value 0 (zero) if successful, otherwise an error is returned.

414 IODeviceControl

Related Functions IODeviceInfo, IODeviceStats, TagRead, TagWrite

Examples
IODeviceControl(4, 0, 1); ! Disable I/O Device 4

IODeviceInfo
Description Gets information about a specified I/O Device.
For remote I/O Devices, you should only call this function on the I/O Server on which the I/O
Device is defined.
Syntax IODeviceInfo(IODevice, Type)

IODevice .........The number or name of the I/O Device. If you call this function from an I/O
server, you can use the I/O Device name. If you call this function from a client,
you should use the I/O Device number.

Type.................The type of information:

0 .... Name of I/O Device

1 .... Protocol of I/O Device
2 .... Protocol address
3 .... State (1 = running, 2 = standby, 16 = offline)
4 .... Last generic error
5 .... Last driver error
6 .... Disabled flag
7 .... Statistics, minimum read time
8 .... Statistics, maximum read time
9 .... Statistics, average read time
10 ... I/O Server state (1 = running, 2 = standby, 16 = offline, only valid on an
I/O Server).
11 ... Unit number
12 ... Configured I/O server name
13 ... Configured Port name
14 ... Configured startup mode
15 ... Configured comment
 IODeviceInfo 415

16.... The primary I/O server name the client uses to communicate to this device
17.... The I/O Server the client is using to communicate to this device. Will be
Standby if the Primary is down.
18 State of the remote unit:
0 = Remote unit is disconnected and OK.
1 = Remote unit is connected and online.
2 = Remote unit is in the dial queue.
16 = Remote unit is disconnected and offline.
32 = Remote unit is disconnected and disabled.
19.... Number of successful attempts to communicate with the scheduled I/O
Device.
20.... Number of failed attempts to communicate with the scheduled I/O Device.
21.... Write mode: Write On Request, and normal (as per schedule defined in the
Express Communications Wizard).
22.... Number of queued read requests for the scheduled I/O Device.
23.... Number of queued write requests for the scheduled I/O Device.
24.... The cache timeout (in milliseconds).

Return Value The type of information (as a string).

Related Functions IODeviceControl, IODeviceStats, TagRead, TagWrite
Examples
sName = IODeviceInfo(20, 0); ! Get name of I/O Device 20

IODeviceStats
Description Gets statistical information for all I/O Devices, and displays the information in a dialog box.
Syntax IODeviceStats()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions IODeviceInfo
Examples
IODeviceStats(); ! display all I/O Device information
416 IsError

IsError
Description Gets the current error value. The error value is set when any error occurs, and is reset after this
function is called. You can call this function if user error-checking is enabled or disabled.
You should call this function as soon as possible after the operation to be checked, because the
error code could be changed by the next error.
Syntax IsError()

Return Value The current error value. The current error is reset to 0 after this function is called.
Related Functions ErrSet
Examples
! Enable user error-checking.
ErrSet(1);
! Invalid ArcSine.
Ac=ArcSin(20.0);
! Sets ErrorVariable to 274 (overflow).
ErrorVariable=IsError()

KerCmd
Description Executes a command in a Kernel window.
Syntax KerCmd(Window, sCommand)

Window ...........The name of the Kernel window.

sCommand.......The command to execute in the Kernel window.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspKernel, TraceMsg DumpKernel,

KeyAllowCursor
Description Allows (or disallows) the command cursor to move to the specified AN or to all ANs. The
command cursor normally moves only to ANs that have commands defined.
Syntax KeyAllowCursor(AN, State)

AN ...................The AN where the command cursor can move. If 0, all ANs are implied.
 KeyAllowCursor 417

State.................Allow state:

0 ..... Do not allow the cursor to move to this AN.

1 ..... Allow the cursor to move to this AN.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyGetCursor
Examples
KeyAllowCursor(20,1);
! Allows the command cursor to move to AN20.

KeyAllowCursor(0,1);
! Allows the command cursor to move to any AN.

KeyBs
Description Removes the last key from the key command line. If the key command line is empty, this
function will not perform any action.
You should call this function using a "Hot Key" command (as shown in the example below),
otherwise the backspace character is placed into the key command line and the command does
not execute. A "Hot Key" command is a command that executes as soon as it is placed into the
key command line.
Syntax KeyBs()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyGet
Examples

System Keyboard
Key Sequence *Bs

Command KeyBs()

Comment Define a backspace Hot Key

(" * " represents a HotKey command)

418 KeyBs

/* If "START A B C" is in the key command line and "START" is the

Key Name for the "F1" key: */
KeyBs();
! Removes ASCII "C".
KeyBs();
! Removes ASCII "B".
KeyBs();
! Removes ASCII "A".
KeyBs();
! Removes Key_F1.
KeyBs();
! Performs no action.

KeyDown
Description Moves the command cursor down the page to the closest AN. If an AN-Down cursor override is
specified (in the Page Keyboard database) for the graphics page, the command cursor moves to
that AN instead.
Syntax KeyDown()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyUp, KeyLeft, KeyRight, KeyMove
Examples See KeyDown().

KeyGet
Description Gets the last key code from the key command line. The key is removed from the command line.
Use this function to process the operator key commands directly. You should call this function
from the keyboard event function.
Syntax KeyGet()

Return Value The last key code from the key command line. If the key command line is empty, 0 (zero) is
returned.
Related Functions KeyPeek, KeyPut
Examples
/* If "START A B C" is in the key command line and "START" is the
Key Name for the "F1" key: */
Variable=KeyGet();
! Sets Variable to 67 (ASCII "C").
Variable=KeyGet();
 KeyGet 419

! Sets Variable to 66 (ASCII "B").

Variable=KeyGet();
! Sets Variable to 65 (ASCII "A").
Variable=KeyGet();
! Sets Variable to 170 (the ASCII value of the F1 key (Key_F1)).
Variable=KeyGet();
! Sets Variable to 0.

KeyGetCursor
Description Gets the AN at the position of the command cursor. If you are using groups, and there are
currently two command cursors, the AN for the innermost will be returned. For example, if there
is a cursor for a group as well as a cursor for one of its objects, the AN for the object will be
returned.
Syntax KeyGetCursor()

Return Value The AN at the position of the command cursor. If no cursor is visible, -1 is returned.
Related Functions KeySetCursor
Examples
! If the command cursor is on AN25:
AN=KeyGetCursor();
! Sets AN to 25.

KeyLeft
Description Moves the command cursor left (across the page) to the closest AN. If an AN-Left cursor
override is specified (in the Page Keyboard database) for the graphics page, the command cursor
moves to that AN instead.
Syntax KeyLeft()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyRight, KeyUp, KeyDown, KeyMove
Examples See KeyLeft().
420 KeyMove

KeyMove
Description Moves the command cursor in a specified direction to the closest AN. If an AN cursor override
is specified, the command cursor moves to that AN directly. This function is equivalent to the
KeyUp(), KeyDown(), KeyLeft(), and KeyRight() functions.
Syntax KeyMove(Direction)

Direction .........Direction to move the cursor:

0 .... Do not move

1 .... Left
2 .... Right
3 .... Up
4 .... Down

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyUp, KeyDown, KeyLeft, KeyRight
Examples
KeyMove(1);
! Moves the cursor left.

KeyPeek
Description Gets the key code from the key command line (at a specified offset), without removing the key
from the key command line. An offset of 0 returns the key code from the last position in the key
command line.
Syntax KeyPeek(Offset)

Offset ............... The offset from the end of the key command line.

Return Value The ASCII key code.

Related Functions KeyGet
Examples
! If "A B C" is in the key command line:
Variable=KeyPeek(0);
! Sets Variable to 67 (ASCII "C")
Variable=KeyPeek(2);
! Sets Variable to 65 (ASCII "A")
 KeyPut 421

KeyPut
Description Puts an ASCII key code or Keyboard key code into the last position of the key command line. If
this key completes any command, that command will execute.
Syntax KeyPut(KeyCode)

KeyCode ..........The key code to put into the key command line.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyGet
Examples
KeyPut(Key_F1);
/* Puts "Key_F1" (the Key Code for the "F1" key) into the last position
of the key command line. If "START" is the Key Name for the "F1" key,
this would be equivalent to

KeyPutStr("START"). In either case, "START" will display on the key

command line. */
KeyPut(StrToChar("A"));
/* Puts the Key Code for the "A" key into the last position of the key
command line. */

KeyPutStr
Description Puts a string at the end of the key command line. The string can contain either key names or data
characters. If this string completes any command, that command will execute.
Syntax KeyPutStr(String)

String ...............The string to put into the key command line.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyPut
Examples
KeyPutStr("START ABC");
! Places "START ABC" at the end of the key command line.
KeyPutStr("TURN PUMP 1 ON");
! Places "TURN PUMP 1 ON" at the end of the key command line.
422 KeyReplay

KeyReplay
Description Replays the last key sequence (except for the last key, which would execute the command). This
function is useful when a command is to be repeated. To call this function from the keyboard,
use a Hot Key " * " (asterisk) command, otherwise the KeyReplay() function itself is replayed.
Syntax KeyReplay()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyReplayAll
Examples If the previous contents of the key command line were:
"START ABC ENTER"

KeyReplay();
! Replays "START ABC".

KeyReplayAll
Description Replays the last key sequence and executes the command. To call this function from the
keyboard, use a Hot Key " * " (asterisk) command, otherwise the KeyReplayAll() function itself
is replayed.
Syntax KeyReplayAll()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyReplay
Examples If the previous contents of the key command line were:
"START ABC ENTER"

KeyReplayAll();
! Replays "START ABC ENTER" and executes the command.

KeyRight
Description Moves the command cursor right (across the page) to the closest AN. If an AN-Right cursor
override is specified (in the Page Keyboard database) for the graphics page, the command cursor
moves to that AN instead.
 KeyRight 423

Syntax KeyRight()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyLeft, KeyUp, KeyDown, KeyMove
Examples See KeyRight().

KeySetCursor
Description Displays the command cursor at a specified AN. A keyboard command must exist, or you must
first call the KeyAllowCursor() function (at the AN) to allow the cursor to move to the AN. If
the AN does not exist, or if a command does not exist at that AN, or if KeyAllowCursor() has
not been called, the command cursor does not move.
Syntax KeySetCursor(AN)

AN....................The AN where the command cursor will be displayed.

Return Value If the AN does not exist, or if a command does not exist at that AN, or if KeyAllowCursor() has
not been called, the return value is 1. Otherwise, the function will return 0.
Related Functions KeyGetCursor, KeyAllowCursor
Examples
! Move the command cursor to AN20.
KeySetCursor(20);

KeySetSeq
Description Adds a keyboard sequence to the current page at runtime. The key sequence is only added to the
current window. When the page is closed, the keyboard sequence is deleted.
Syntax KeySetSeq(sKeySeq, AN, Fn)

sKeySeq ...........The keyboard sequence.

AN....................The AN where the keyboard sequence will apply. If you set AN to 0 (zero), the
keyboard sequence will apply to all ANs on the page.

Fn ....................The function to call when the keyboard sequence matches. This function must be
a callback function.

Return Value 0 (zero) if successful, otherwise an error is returned.

424 KeySetSeq

Related Functions DspButton, DspButtonFn

Examples
/* Set the key sequence and call the "Callback" function when the
sequence is found. */
KeySetSeq("F2 ### Enter", 0, Callback);

! This function is called when the key sequence is found.

INT
FUNCTION
CallBack()
INT Value;
! Get user data.
Value=Arg1;
.
.
RETURN 0;
END

KeyUp
Description Moves the command cursor up the page to the closest AN. If an AN-Up cursor override is
specified (in the Page Keyboard database) for the graphics page, the command cursor moves to
that AN.
Syntax KeyUp()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions KeyDown, KeyLeft, KeyRight, KeyMove
Examples See KeyUp().

LanguageFileTranslate
Description Translates an ASCII file into a local language. Use this function to translate RTF reports for
viewing on Display Client screens.
The local language used by this function is specified by the [Language]LocalLanguage
parameter - you must set this parameter accordingly.
Syntax LanguageFileTranslate(sSourceFile, sDestFile)

sSourceFile......The name of the ASCII file containing multi-language text, which will be copied
and translated. You should specify the full path or use path substitution. The
path and name should be contained within quotation marks.
 LanguageFileTranslate 425

sDestFile..........The name of the destination file which will be created/replaced with the
local/translated version of the source file. You should specify the full path or use
path substitution. The path and name should be contained within quotation
marks.

Return Value TRUE (1) if successful, otherwise FALSE (0).

Related Functions SetLanguage, StrToLocalText.
Examples
/* Translates the text in Shift.RTF and saves it in LShift.RTF. */
LanguageFileTranslate("c:\Citect\data\Shift.RTF","c:\Citect\data\LShift.
RTF");

/* Translates the text in [Data]:Shift.RTF and saves it in

[LocalData]:LShift.RTF. */
LanguageFileTranslate("[Data]:Shift.RTF","[LocalData]:LShift.RTF");

LeaveCriticalSection
Description Relinquishes the current thread's ownership of a critical section. Once ownership is relinquished,
access to the critical section is available to the next thread that requests it (using the
EnterCriticalSection() function). If a thread has been waiting for access, it will be granted at this
point.
LeaveCriticalSection() must be called once for each EnterCriticalSection() used.
Syntax LeaveCriticalSection(sName)

sName ..............The name of the critical section. The name must be entered in quotation marks.

Return Value This function does not return a value.

Related Functions EnterCriticalSection
Examples
/* Request access to critical section, execute code and relinquish
ownership of critical section. */

FUNCTION
MyCriticalFunction()
EnterCriticalSection("MyCritical");
// critical code is placed here
LeaveCriticalSection("MyCritical");
END
426 Ln

Ln
Description Calculates the natural (base e) logarithm of a number.
Syntax Ln(Number)

Number............ Any number.

Return Value The natural (base e) logarithm of Number.

Related Functions Log
Examples
Variable=Ln(2);
! Sets Variable to 0.6931...

Log
Description Calculates the base 10 logarithm of a number.
Syntax Log(Number)

Number............ Any number.

Return Value The base 10 logarithm of Number.

Related Functions Ln
Examples
Variable=Log(100);
! Sets Variable to 2 (i.e. 100=10 to the power of 2).

Login
Description Logs a user into the Citect system, and gives users access to the areas and privileges assigned to
them in the Users database. Only one user can be logged into a computer at any one time. If a
user is already logged in when a second user logs in, the first user is automatically logged out.
At startup, or when the user logs out, a default user is active, with access to area 0 (zero) and
privilege 0 (zero) only. Use the LoginForm() function to display a form for logging in to the
system.
Syntax Login(UserName, Password)

UserName........ The user's name, as defined in the Users database.

 Login 427

Password .........The user's password, as defined in the Users database.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions LoginForm, Logout, LogoutIdle, Message, Input
Examples
/* Log in a user whose user name is "FRED" and whose password is "ABC".
*/
Login("FRED","ABC");

LoginForm
Description Displays a form in which a user can log in to the Citect system by entering their name and
password. If the login is correct, the user is logged into the Citect system with the area(s) and
privilege(s) assigned to them in the Users database.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax LoginForm()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Login
Examples

System Keyboard
Key Sequence Login

LoginForm Display the Login form

Comment Allow user login

428 LoginForm

Buttons
Text Operator Login

LoginForm Display the Login form

Comment Allow user login

Logout
Description Logs the current user out of the Citect system. Citect continues to run, but with access to area 0
(zero) and privilege 0 (zero) only.
Syntax Logout()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Login, LoginForm, LogoutIdle, UserInfo, Message, Input
Examples
/* Log the current user out of the system. */
Logout();

LogoutIdle
Description Sets an idle time for logging out the current user. If the current user does not execute a
command within the specified idle time, a prompt is displayed. If the prompt is ignored, then the
user is logged out. For all users to have the same idle time, you would call this function at
startup. Otherwise, you can call the function from the Users database to specify an idle time for
each user.
Syntax LogoutIdle(Idle)

Idle .................. The number of minutes the user must be idle before logout will occur. Set Idle
to -1 to disable the current logout timeout.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Logout, Login, LoginForm
Examples
 LogoutIdle 429

Users
User Name Operator1

LoginForm LogoutIdle(5)

Comment Logs the user out after five minutes

LowByte
Description Gets the low-order byte of a two-byte integer.
Syntax LowByte(TwoByteInteger)

TwoByteInteger A two-byte integer.

Return Value The low-order byte (i.e. | - | X |)

Related Functions HighByte, LowWord, HighWord
Examples
Variable=LowByte(0x5678);
! Sets Variable to 0x78.

LowWord
Description Gets the low-order word of a four-byte integer.
Syntax LowWord(FourByteInteger)

FourByteInteger A four-byte integer.

Return Value The low-order word (i.e. | - | - | X | X |)

Related Functions HighWord, LowByte, HighByte
Examples
Variable=LowWord(0x12345678);
! Sets Variable to 0x5678
430 MailError

MailError
Description Gets the last mail error code. The error code is extracted from the MAPI mail system, and
explains what caused the MAPI function to fail.
Syntax MailError()

Return Value 0 (zero) if successful, otherwise an error is returned. Refer also to MAPI errors.
Related Functions MailLogon, MailLogoff, MailSend, MailRead
Examples
! Logon to the mail system
IF MailLogon("RodgerG", "password", 0) THEN
error = MailError();
!do what is required
END

MailLogoff
Description Logs off from the mail system. You should log off the mail system when all mail operations are
complete. Citect automatically logs off the mail system on shutdown.
Syntax MailLogoff()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MailLogon, MailSend, MailRead, MailError
Examples
! Send the report to Rodger
MailLogon("Andrew", "password", 0);
MailSend("Rodger Gaff", "Report", "This is the weekly report",
"[data]:weekly.txt", 0);
MailLogoff();

MailLogon
Description Logs on to the mail system. You must call this function before any other mail function.
The mail system uses the MAPI standard interface, so you can use any mail system that supports
this standard.
You should log on to the mail system when Citect starts, and log off only at shutdown. (The
logon procedure can take a few seconds to complete.) You can only log on as one user at a time
for each computer, so you can only read mail for this user name.
 MailLogon 431

Syntax MailLogon(sName, sPassword, iMode)

sName ..............The name of the mail user. This name is the user's mail box name (the unique
shorthand name, not the full user's name).

sPassword........The password of the mail user.

iMode...............The mode of the logon:

0 ..... Normal logon.

2 ..... Get unique logon, do not share existing mail client logon.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MailLogoff, MailSend, MailRead, MailError
Examples
! Send the report to James
MailLogon("RodgerG", "password", 0);
MailSend("James Glover", "Report", "This is the weekly report",
"[data]:weekly.txt", 0);
MailLogoff();

MailRead
Description Reads a standard mail message. The mail message can contain text, an attached file, or both.
Before you can use this function, you must use the MailLogon() function to log on to the mail
system. You can only read mail sent to the user name specified in the MailLogon() function.
Syntax MailRead(sName, sSubject, sNote, sFileName, iMode)

sName ..............The name of the mail user who sent the message.

sSubject............The subject text of the mail message.

sNote................The note section of the message. If the message is longer than 255 characters,
Citect will save the message in a file and return the file name in sNote. Use the
file functions to read the message. The name of the file will be in the form
CTxxxxx where x is a unique number. You must delete the file after you have
finished with the mail message.

sFileName........The name of any attached file. If there is no attached file in the message, specify
sFileName as an empty string "".
432 MailRead

iMode ..............The mode of the read:

0 ..... Read a message. If no message is available, wait for a message.

1 ..... Read a message. If no message is available, return with an error code.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MailLogon, MailLogoff, MailSend, MailError
Examples
! Logon to the mail system
MailLogon("RodgerG", "password", 0);
! Read a message. Don't wait if no message
IF MailRead(sName, sSubject, sNote, sFileName, 1) = 0 THEN
! got message now do something with it
END

WHILE TRUE DO
! wait for a mail message
MailRead(sName, sSubject, sNote, sFileName, 0);

END;
MailLogoff();

MailSend
Description Sends a standard mail message. The mail message can contain text, an attached file, or both.
Before you can use this function, you must use the MailLogon() function to log on to the mail
system. You can only send mail from the user name specified in the MailLogon() function. You
can send mail to any mail user or to another Citect Display Client.
Syntax MailSend(sName, sSubject, sNote, sFileName, iMode)

sName.............. The name of the mail user who will receive the message. This name is the user's
full name (not their mailbox name).

sSubject ...........The subject text of the mail message (a short description of what the message is
about).

sNote ...............The note section of the message (the main section of the message text). You can
enter up to 255 characters, or a file name for longer messages. If you enter a file
name, set iMode to 1.

sFileName .......The name of any attached file. If there is no attached file in the message, set
sFileName to an empty string "".
 MailSend 433

iMode...............The mode of the send:

0 ..... Normal mail message.

1 ..... The sNote argument is the name of a text file to send as the note.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MailLogon, MailLogoff, MailRead, MailError
Examples
! Logon to the mail system
MailLogon("RodgerG", "password", 0);

! send the report to Andrew

MailSend("Andrew Bennet", "Report", "Attached is the weekly report",
"[data]:weekly.txt", 0);

! send hello message to Jane

MailSend("Jane Clancy", "Hello", "Hello there Jane", "", 0);

! send a big note to Nigel

MailSend("Nigel Colless", "Big Message", "[data]:message.txt", "", 1);
MailLogoff();

Max
Description Gets the higher of two numbers.
Syntax Max(Number1, Number2)

Number1 ..........The first number.

Number2 ..........The second number.

Return Value The higher of numbers Number1 and Number2.

Related Functions Min
Examples
Variable=Max(24,12);
! Sets Variable to 24.
434 Message

Message
Description Displays a message box on the screen and waits for the user to select the [OK] or [Cancel]
button.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax Message(Title, Prompt, Mode)

Title ................. The title of the message box.

Prompt.............The prompt displayed in the message box.

Mode ...............The mode of the message box:

0 ..... OK button
1 ..... OK and Cancel button
16 .. Stop Icon
32 .. Question Icon
48 .. Exclamation Icon
64 .. Information Icon
Select more than one mode by adding the modes. For example, set Mode to 33
to display the [OK] and [Cancel] buttons and the Question icon.

Return Value 0 (zero) if successful, otherwise an error is returned. If the user presses the Cancel button the
function returns an error code of 299.
Related Functions Input
Examples
/* Display an error message in a message box. */
IF Total<>100 THEN
Message("Error","Total not 100%",48);
END

Min
Description Returns the lower of two numbers.
Syntax Min(Number1, Number2)

Number1.......... The first number.

 Min 435

Number2 ..........The second number.

Return Value The lower of numbers Number1 and Number2.

Related Functions Max
Examples
Variable=Min(24,12);
! Sets Variable to 12.

MsgBrdcst
Description Broadcasts a message to all the clients of a server. You should call this function only on a Citect
server. The message is only received by clients that have a current message session (opened
with the MsgOpen() function).
Syntax MsgBrdcst(Name, Type, Str)

Name................The name of the Citect server.

Type .................The message number.

Str ....................The message text.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MsgOpen, MsgClose, MsgRead, MsgWrite, MsgRPC
Examples
! Send a message to all alarm clients.
MsgBrdcst("Alarm",0,"Alarm Occurred");

MsgClose
Description Closes a message. After the message is closed, the message post function (the callback function
specified in the MsgOpen() function) is not called if a message is received. When the server side
is closed, all clients are closed. When the client side is closed, only the specified client is closed.
Syntax MsgClose(Name, hMsg)

Name................The name of the Citect server.

hMsg ................The message handle, returned from the MsgOpen() function. The message
handle identifies the table where all data on the associated message is stored.
436 MsgClose

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MsgOpen, MsgRPC, MsgRead, MsgWrite
Examples
MsgClose("Alarm",hMsg);

MsgGetCurr
Description Gets the handle of the client message that called the report or remote procedure that is currently
running. You can call this function only in a report or a remote procedure call.
If the report was called by a client, this function returns that client message handle. The report
can then send a message back to the client. If a function was called remotely by MsgRPC(), this
function returns the message handle for the remote client.
Syntax MsgGetCurr()

Return Value The handle for the client message. The message handle identifies the table where all data on the
associated message is stored. The function returns -1 if no client called the report or function.
Related Functions MsgOpen, MsgRPC
Examples
! Send message back to the client.
hMsg=MsgGetCurr();
IF hMsg<>-1 THEN
MsgRPC(hMsg,"Prompt","^"Hello Client from Report Server^"",1);
END

MsgOpen
Description Opens a message session to a Citect server. You can specify a message post function - a
callback function that is automatically called when a message arrives. In this function you can
call MsgRead() to get the message, and perform other tasks common to your message sessions.
You can then call MsgWrite() to send a message back to the caller, MsgRPC() to call a
procedure on the caller, and so on.
You can open a client-server message session or a session between redundant servers. This
function does not create extra network sessions - it uses Citect's existing sessions, so you create
sessions to the "Alarm", "Report", "Trend", or "IOServer" servers.
Syntax MsgOpen(Name, Mode, Fn)

Name ............... The name of the server to open, either:

 MsgOpen 437

For Mode 0, 1, or 3 "Alarm", "Report", "Trend", or "IOServer"

For Mode 2 The default computer name, as set in the [Lan]Node parameter.

Mode................The mode of the message session to open:

0 .... Open the client side.

1 .... Open the server side.
2 .... Open a session from a server to the default computer name. Set Name to
the computer name of the computer, as defined by the [LAN]Node
parameter.
3 ..... Open a message session between redundant servers. (Display Clients
cannot tell which server they are connected to or if something has changed
on the server. All changes should be performed on the redundant server as
well.)

Fn ....................The message post function, i.e. a callback function for the message event. Set
Fn to 0 if no event callback function is required.

Return Value The message handle, or -1 if the session cannot be opened. The message handle identifies the
table where all data on the associated message is stored.
Related Functions MsgRPC, MsgClose, MsgRead, MsgWrite
Examples
! Open message on the Client Side
Client=MsgOpen("Alarm", 0, MsgPostClient);
MsgWrite(hClient,1,"MyMessage");

! This function is called when the Client gets a message

INT
FUNCTION
MsgPostClient()
INT Type;
STRING Str;

MsgRead(Type,Str);
Prompt("ClientGotMessage "+Type:###+"Str "+Str);
RETURN 0;
END

MsgRead
Description Reads a message from a message session. You can call this function only in a message post
function (the callback function specified in the MsgOpen() function), to read the current
message.
438 MsgRead

The Type and Str variables of this function return the message number and the text of the
message. The return value of this function is the message handle (allowing a response to be sent
back if required).
You must open the message session using the MsgOpen() function, to enable the callback
function.
Syntax MsgRead(Type, Str)

Type.................The message number.

Str....................The message text.

Return Value The message handle of the message being read.

Related Functions MsgOpen, MsgClose, MsgRPC, MsgWrite
Examples
/* This function will read a message from the session and if Type=1,
will display the string as a prompt. If Type=2 then the speaker beeps
and an acknowledgment is sent back to the caller. */
INT
FUNCTION
MsgPostClient()
INT Type;
STRING Str;
INT hMsg;

hMsg=MsgRead(Type,Str);
IF Type=1 THEN
Prompt("Message"+Str);
ELSE
IF Type=2 THEN
Beep();
MsgWrite(hMsg,2,"DONE");
END
END

MsgRPC
Description Calls a remote procedure on another Citect computer. You can call any of the in-built Cicode
functions remotely, or your own functions. You pass the Name of the function as a string, not as
the function tag, and pass all the arguments for that function in Arg.
You can call the function in synchronous or asynchronous Mode. In synchronous mode,
MsgRPC() does not return until the remote function is called and the result is returned. In
asynchronous mode, MsgRPC() returns before the function is called, and the result cannot be
returned.
 MsgRPC 439

Syntax MsgRPC(hMsg, Name, Arg, Mode)

hMsg ................The message handle, returned from the MsgOpen() function. The message
handle identifies the table where all data on the associated message is stored.

Name................The name of the function to call remotely, as a string.

Arg...................The arguments to pass to the function, separated by commas (,). Enclose string
arguments in quotes "" and use the string escape character (^) around strings
enclosed within a string. If you do not enclose the string in quotes, then the
string is only the first tag found.

Mode................The mode of the call:

0 .... Blocking mode - synchronous.

1 .... Non-blocking mode - asynchronous.

Return Value The result of the remote function call (as a string). If the function is called in asynchronous
mode the result of the remote function cannot be returned, so an empty string is returned.
Related Functions MsgOpen, MsgClose, MsgRead, MsgWrite
Examples
! Call remote procedure, call MyRPC() on server. Wait for result
Str=MsgRPC(hMsg,"MyRPC","Data",0);

! Call remote procedure, pass two strings. Don't wait for call to
complete.
! be careful of your string delimiters as shown.
MsgRPC(hMsg,"MyStrFn","^"First string^",^"Second string^"",1);

! Call remote procedure, pass Cicode string. Don't wait for call to
complete.
STRING sMessage = "this is a message";
MsgRPC(hMsg,"MyStrFn","^"" + sMessage + "^"",1);

! These functions could be used to acknowledge an alarm by record from

any Citect Client on the network.

! The AlmAck() function is initialised by the Display Client (Don't

forget that servers are also Display Clients.)
! The Alarm tag is passed into the function as a string and a message is
sent to the Alarms Server to initialise
! the AlmAckMsg() function.

FUNCTION
AlmAck(String AlmTag)
440 MsgRPC

INT hAlarm1;

hAlarm1 = MsgOpen("Alarm", 0, 0);

MsgRPC(hAlarm1,"AlmAckMsg",AlmTag,1);
MsgClose("Alarm", hAlarm1);
END

! The AlmAckMsg() function is executed on the Alarms Server that the

Display Client is connected to. This could be
! either the primary or standby Alarms Server. The function performs the
alarm acknowledge.

FUNCTION
AlmAckMsg(String AlmTag)
AlarmAckRec(AlarmFirstTagRec(AlmTag,"",""));

END

MsgWrite
Description Writes a message to a message session. The message is sent to the remote computer's callback
function and can be read by calling MsgRead(). If the remote computer has not opened the
session, this message is disregarded.
This function returns immediately after passing the message to Citect. Citect sends the message
over the LAN in the background.
You must first open the message session using the MsgOpen() function, to obtain the message
handle.
Syntax MsgWrite(hMsg, Type, Str)

hMsg................The message handle, returned from the MsgOpen() function. The message
handle identifies the table where all data on the associated message is stored.

Type.................The integer message data, i.e. the message number.

Str....................The message text.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions MsgRead, MsgOpen
Examples
MsgWrite(hMsg,10,"MyMsg");
 Name 441

Name
Description Gets the name of the operator who is currently logged-in to the display system. If this function is
called on a server, it returns the name of the local operator.
Syntax Name()

Return Value The name of the user (as a string).

Related Functions FullName, Login, LoginForm
Examples
/* Display the user name of the current user at AN20. */
DspText(20,0,Name());

ObjectAssociateEvents
Description Allows you to change the ActiveX object’s event class. If you have inserted an object on a
graphics page using Graphics Builder, it allows you to change the event class to something other
than the default of PageName_ObjectName
Syntax ObjectAssociateEvents(sEventClass, hSource)

sEventClass .....The string you would like to use as the event class for the object.

hSource............The source object firing the events which are to be handled by the event handler.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspAnCreateControlObject(),CreateControlObject()

Examples
Inserting ActiveX objects using Cicode…
If you have created an ActiveX object using Cicode (eg. by calling the function
CreateControlObject()), the parameter 'sEventClass' would have required you to define an event
class for the object to enable event handling. If you want to change the class you used, you can
call ObjectAssociateEvents().

Inserting ActiveX objects via Graphics Builder…

442 ObjectAssociateEvents

If you have inserted an ActiveX object in Graphics Builder, runtime will automatically create an
event class for the object in the form PageName_ObjectName. If this is the case, you may want
to change the object's event class.
Using the example of an ActiveX sludge tank controller, the default event class for the object
could be "PageName_AN35". This means any events handlers for the object would take the form
"PageName_AN35_Click" (presuming this example relates to a click event). You may want to
define this more clearly, in which case you can call the following:

// This function redefines the event class for the ActiveX sludge tank
controller at AN35 to "SludgeTank". //

ObjectAssociateEvents ("SludgeTank", ObjectByName(AN35));

.
.
With the event class for the object now defined as "SludgeTank", the event handlers can take the
form "SludgeTank_Click".
This would be particularly useful if you define a number of event handlers in relation to an object
that will eventually be copied to other graphics pages, as it will eliminate the need to redefine the
event handlers to identify the default event class associated with each new placement of the object.

ObjectByName
Description Retrieves an ActiveX object. This is useful when you know the object by name only (this will
often be the case for objects created during configuration, rather than those created at runtime
using a Cicode function).
Syntax ObjectByName(sName)

sName.............. The name for the object in the form of "AN" followed by its AN number, eg.
"AN35". This name is used to access the object.

Return Value The requested object, if successful, otherwise an error is generated.

Related Functions DspAnCreateControlObject(),CreateObject(),CreateControlObject()
Examples See CreateControlObject().

OnEvent
Description Sets an event callback function for an event type. The callback function is called when the event
occurs.
 OnEvent 443

Using callback functions saves polling or checking for events. Callback functions have no
arguments and must return an integer. The return value of the callback will depend on the type
of event. Set Fn to 0 to disable the event.
Syntax OnEvent(Type, Fn)

Type .................The type of event:

0 .... The mouse has moved. When the mouse moves the callback function is
called. The return value must be 0.
1 .... A key has been pressed. When the user presses a key, the callback function
is called after Citect checks for hot keys. If the return value is 0, Citect
checks for key sequences. If the return value is not 0, Citect assumes that
you will process the key and does not check the key sequence. It is up to
you to remove the key from the key command line.
NOTE:....... If you are using a right mouse button click as an event, you should
read about the ButtonOnlyLeftClick parameter.
2 .... Error event. This event is called if an error occurs in Cicode, so you can
write a single error function to check for your errors. If the return value is
0, Citect continues to process the error and generates a hardware error - it
may then halt the Cicode task. If the return value is not 0, Citect assumes
that you will process the error, and continues the Cicode without generating
a hardware error.
3 ..... Page user communication error. A communication error has occurred in
the data required for this page. If the return value is 0 (zero), Citect still
animates the page. If the return value is not zero, Citect does not update the
page.
4 ..... Page user open. A new page is being opened. This event allows you to
define a single function that is called when all pages are opened. The return
value must be 0.
5 ..... Page user close. The current page is being closed. This event allows you to
define a single function that is called when all pages are closed. The return
value must be 0.
6 ..... Page user always. The page is active. This event allows you to define a
single function that is called when all pages are active. The return value
must be 0.
7 ..... Page communication error. A communication error has occurred in the
data required for this page. Reserved for use by Citect.
8 ..... Page open. This event is called each time a page is opened. Reserved for
use by Citect.
444 OnEvent

9 ..... Page close. This event is called each time a page is closed. Reserved for
use by Citect.
10 ... Page always. This event is called while a page is active. Reserved for use
by Citect.
11..17 Undefined.
18 ... Report start. The report server is about to start a new report. This event is
called on the report server. The return value must be 0.
19 ... Device history. A device history has just completed. The return value must
be 0.
20 ... Login. A user has just logged in.
21 ... Logout. A user has just logged out.
22 ... Trend needs repainting. This event is called each time Citect re-animates a
real-time trend or scrolls an historical trend. You should use this event to
add additional animation to a trend, because Citect deletes all existing
animation when a trend is re-drawn. (For example, if you want to display
extra markers, you must use this event.)
23 ... Hardware error occurred.
24 ... Keyboard cursor moved. This event is called each time the keyboard
command cursor moves. The cursor can be moved by the cursor keys, the
mouse, or the Cicode function KeySetCursor(). Note that you can find
where the keyboard command cursor is located by calling the function
KeyGetCursor().
25 ... Network shutdown. A Shutdown network command has been issued.
26 ... Runtime system shutdown and restart. (Required because of configuration
changes.)
27 ... Event. An event has occurred.
28 ... Accumulator. An accumulator has logged a value.
29 ... Slider. A slider has been selected.
30 ... Slider. A slider has moved.
31 ... Slider. A slider has been released (i.e. stopped moving).

NOTE: .......1) While responding to slider events 29, 30, and 31, you can set any
variables but you cannot call functions that cause immediate changes
to animations on the page (e.g. DspText() and DspSym()).
2) Types 29, 30, & 31 relate only to V3.xx and V4.xx animations,
and will be superseded in future releases.
32 ... Shutdown. Citect is being shutdown.
 OnEvent 445

33... 127 Reserved for future Citect use.

128... 256... User defined events. These events are for your own use.

Fn ....................The function to call when the event occurs. This callback function must have no
arguments, so you specify the function with no parentheses (). The callback
function must return INT as its return data type. You cannot specify a Citect in-
built function as a callback function.

Set Fn to 0 to disable the event.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GetEvent, CallEvent, ChainEvent
Examples
OnEvent(1,KeyFn);
! Calls a function named KeyFn().
INT
FUNCTION
KeyFn()
INT Key;
Key=KeyPeek(0);

IF Key=27 THEN
Prompt("ESC pressed");
RETURN 1;
ELSE
RETURN 0;
END
END

OnEvent(0,MouseFn);
! Calls a function named MouseFn().
INT
FUNCTION
MouseFn()
INT X,Y;
DspGetMouse(X,Y);
RETURN 0;
END

PackedRGB
Description Returns a packed RGB colour based on specified red, green, and blue values.
Syntax PackedRGB(nRed, nGreen, nBlue)

nRed.................The red component of the desired packed RGB colour.

446 PackedRGB

nGreen.............The green component of the desired packed RGB colour.

nBlue ...............The blue component of the desired packed RGB colour.

Return Value The packed RGB colour value - if successful, otherwise an error is returned.
Related Functions CitectColourToPackedRGB

PackedRGBToCitectColour
Description Converts a packed RGB colour into the nearest equivalent Citect colour.
Syntax PackedRGBToCitectColour(nPackedRGB)

nPackedRGB ...The packed RGB colour.

Return Value The Citect colour value - if successful, otherwise an error is returned.
Related Functions CitectColourToPackedRGB

PageAlarm
Description Displays a category of active alarms on the alarm page. To use this function, you must use the
Graphics Builder to create a page called "Alarm" (using the alarm template).
NOTE: The operation of this function has changed. In Version 2.xx this function displayed the
in-built alarm page from the Include project.
Syntax PageAlarm(Category)

Category..........The alarm category to display. Set to 0 (the default) to display all alarm
categories.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageDisabled, PageHardware
Examples
 PageAlarm 447

System Keyboard
Key Sequence AlarmPage

Command PageAlarm(0)

Comment Display all active alarms on the alarm

page

System Keyboard
Key Sequence Alarm ### Enter

Command PageAlarm(Arg1)

Comment Display a specified category of active

alarms on the alarm page

PageDisabled
Description Displays a category of disabled alarms on the alarm page. To use this function, you must use the
Graphics Builder to create a page called "Disabled" (using the disabled template).
NOTE: The operation of this function has changed. In Version 2.xx this function displayed the
in-built disabled alarm page from the Include project.
Syntax PageDisabled(Category)

Category ..........The alarm category to display. Set to 0 (the default) to display all alarm
categories.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageAlarm
Examples
448 PageDisabled

System Keyboard
Key Sequence DisabledPage

Command PageDisabled(0)

Comment Display all disabled alarms on the alarm

page

System Keyboard
Key Sequence Disabled ### Enter

Command PageDisabled(Arg1)

Comment Display a specified category of disabled

alarms on the alarm page

PageDisplay
Description Displays a graphics page in the active window. The page must be in one of the operator's current
areas. You can specify either the Page Name or the Page Number of the graphics page.
Citect saves the current page (onto a stack) before it displays the required page. You can call
PageLast() to re-display the pages on the stack.
You cannot call this function from the Exit command field (see Page Properties) or a Cicode
Object.
Syntax PageDisplay(Page)

Page ................The Page Name or Page Number of the page to display (in quotation marks "").

Return Value 0 (zero) if the page is successfully displayed, otherwise an error is returned.
Related Functions PageGoto, PageLast
Examples
 PageDisplay 449

Buttons
Text Mimic Page

Command PageDisplay("Mimic")

Comment Display the "Mimic" page

System Keyboard
Key Sequence Page ############## Enter

Command PageDisplay(Arg1)

Comment Display a specified page

PageDisplay("MIMIC1");
! Displays page "MIMIC1".

PageDisplay("MIMIC2");
/* Displays page "MIMIC2" and places page "MIMIC1" onto the PageLast
stack. */

PageDisplay("10");
/* Displays page "10" and places page "MIMIC2" onto the PageLast stack.
*/

PageLast();
/* Displays the last page on the stack, i.e. page "MIMIC2" and removes
it from the stack. */

PageFile
Description Displays a file on the page. After the file is displayed, you can scroll up and down through the
file. To use this function, you must use the Graphics Builder to create a page called "File"
(using the file template).
NOTE: The operation of this function has changed. In Version 2.xx this function displayed the
in-built file page from the Include project.
Syntax PageFile(sName)

sName ..............The name of the file to display.

Return Value 0 (zero) if the file is successfully displayed, otherwise an error is returned.
450 PageFile

Related Functions DspFile

Examples

System Keyboard
Key Sequence File ######## Enter

Command PageFile(Arg1)

Comment Display the specified file on the page

PageFileInfo
Description Returns the width or height of an unopened page.
Syntax PageFileInfo(sPageName, nMode)

sPageName......The name of the page you would like to retrieve size information for.

nMode .............Retrieves either the width or the height of the specified page in pixels.

0 ..... returns the page width

1 ..... returns the page height

Return Value The height or width of the specified page in pixels, depending on the value set for nMode.

PageGetInt
Description Gets a local page-based integer. Page-based variables are local to each display page. If two or
more windows are displayed, each window has a unique copy of the variable. You can use these
variables in Cicode to keep track of variables unique to each window.
NOTE: You can find out the current setting for [Page]ScanTime parameter, by calling this
function as follows: PageGetInt(-2)
Syntax PageGetInt(Offset)

Offset ............... The offset in the array of integers.

 PageGetInt 451

Return Value The value of the integer.

Related Functions PageSetInt, PageGetStr, PageSetStr
Examples

PageGetStr
Description Gets a local page-based string. Page-based variables are local to each display page. If two or
more windows are displayed, each window has a unique copy of the variable. You can use these
variables in Cicode to keep track of variables unique to each window.
Specify the position of the variable in the array in the Offset argument. (The length of the array
is set by the [Page]MaxStr parameter.)
Syntax PageGetStr(Offset)

Offset ...............The offset in the array of strings.

Return Value The string.

Related Functions PageSetInt, PageGetInt, PageSetStr
Examples

PageGoto
Description Displays a graphics page in the active window. The page must be in one of the operator's current
areas. You can specify either the Page Name or the Page Number of the graphics page. This
function is similar to PageDisplay(), however PageGoto() does not put the current page onto the
PageLast stack.
You cannot call this function from the Exit command field (see Page Properties) or a Cicode
Object.
Syntax PageGoto(Page)

Page.................The Page Name or Page Number of the page to display (in quotation marks "").

Return Value 0 (zero) if the page is successfully displayed, otherwise an error is returned.
Related Functions PageDisplay
Examples
PageDisplay("MIMIC1");
! Displays page "MIMIC1".
452 PageGoto

PageDisplay("MIMIC2",);
/* Displays page "MIMIC2" and places page "MIMIC1" onto the PageLast
stack. */

PageGoto("10");
/* Displays page "10". Page "MIMIC2" is not placed onto the PageLast
stack. */

PageHardware
Description Displays the active hardware alarms on the alarms page. To use this function, you must use the
Graphics Builder to create a page called "Hardware" (using the alarm template).
NOTE: The operation of this function has changed. In Version 2.xx this function displayed the
in-built hardware alarm page from the Include project.
Syntax PageHardware()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageAlarm
Examples

System Keyboard
Key Sequence Hardware
Command PageHardware()

Comment Display active hardware alarms on the

hardware alarms page

PageInfo
Description Gets information about the current page.
Syntax PageInfo(Type)

Type.................The type of page information required:

0 ..... Page Name

1 ..... Page Number
 PageInfo 453

2 ..... Page Title

3 ..... Display filename
4 ..... Symbol filename
5 ..... Next Page Name
6 ..... Previous Page Name
7 ..... Previous display count, incremented at each refresh
8 ..... Parent window number (returns -1 if there is no parent)
9 ..... First child window number (returns -1 if there are no children)
10... Next child in child link (returns -1 for end of the list)
11... Window mode (set by the WinNewAt() function)
12... Width of window
13... Height of window
14... X position of window
15... Y position of window

Return Value The information (as a string).

Related Functions PageDisplay
Examples
! If currently on page "MIMIC1";
Variable=PageInfo(0);
! Sets Variable to "MIMIC1".

PageLast
Description Displays the graphics page that was last displayed. With this function, you can successively
recall the last ten pages that were displayed.
Graphics pages displayed using this command cannot be subsequently recalled.
You cannot call this function from the Exit command field (see Page Properties) or a Cicode
Object.
Syntax PageLast()

Return Value 0 (zero) if the page is successfully displayed, otherwise an error is returned.
Related Functions PagePeekLast, PagePopLast, PagePushLast
454 PageLast

Examples

Buttons
Text Last Page
Command PageLast()

Comment Display the graphics page that was last

displayed

PageDisplay("MIMIC1");
! Displays page "MIMIC1".

PageDisplay("MIMIC2");
/* Displays page "MIMIC2" and places page "MIMIC1" onto the PageLast
stack. */

PageDisplay("10");
! Displays page "10" and places page "MIMIC2" onto the PageLast stack.

PageLast();
/* Displays the last page on the stack, i.e. page "MIMIC2" and removes
it from the stack. */

PageLast();
/* Displays the last page on the stack, i.e. page "MIMIC1" and removes
it from the stack. */

PageLast();
/* Returns an "Out of range" error code as there are no more pages on
the stack.*/

PageMenu
Description Displays a menu page with page selection buttons. A page goto button is displayed for each of
the first 40 pages defined in the project.
Syntax PageMenu()

Return Value 0 (zero) if the page is successfully displayed, otherwise an error is returned.
Related Functions PageGoto, PageLast, PagePrev, PageSelect
Examples
 PageMenu 455

Buttons
Text Menu

Command PageMenu()

Comment Display the menu page

System Keyboard
Key Sequence Menu

Command PageMenu()

Comment Display the menu page

PageNext
Description Displays the next page as specified in the project.
You cannot call this function from the Exit command field (see Page Properties) or a Cicode
Object.
Syntax PageNext()

Return Value 0 (zero) if the page is successfully displayed, otherwise an error is returned.
Related Functions PagePrev
Examples

Buttons
Text Page Next

Command PageNext()

Comment Display the next page in the browse

sequence
456 PageNext

System Keyboard
Key Sequence PageNext

Command PageNext()

Comment Display the next page in the browse

sequence

/* If graphics page 1 is currently displayed, and the graphics page 1

has Next Page Name=10. */
PageNext();
! Displays graphics page 10.

PagePeekLast
Description Gets the Page Name at an offset in the PageLast stack (without removing the page from the
stack).
Syntax PagePeekLast(Offset)

Offset ............... The offset from the end of the PageLast stack. Offset 0 is the last page on the
stack, Offset 1 is the second last page on the stack, etc.

Return Value The Page Name or an empty string if there is no last page.
Related Functions PagePopLast, PagePushLast
Examples
PageDisplay("MIMIC1");
! Displays page "MIMIC1".

PageDisplay("MIMIC2");
/* Displays page "MIMIC2" and places page "MIMIC1" onto the PageLast
stack. */

PageDisplay("10");
! Displays page "10" and places page "MIMIC2" onto the PageLast stack.

PageGoto(PagePeekLast(0));
! Displays page "MIMIC2".

PageGoto(PagePeekLast(1));
! Displays page "MIMIC1".
 PagePopLast 457

PagePopLast
Description Gets the Page Name of the last item on the PageLast stack and removes the page from the stack.
Syntax PagePopLast()

Return Value The page name or an empty string if there is no last page.
Related Functions PageLast
Examples
PageDisplay("MIMIC1");
! Displays page "MIMIC1".

PageDisplay("MIMIC2");
/* Displays page "MIMIC2" and places page "MIMIC1" onto the PageLast
stack. */

PageDisplay("10");
! Displays page "10" and places page "MIMIC2" onto the PageLast stack.

Variable=PagePopLast();
/* Sets Variable to "MIMIC2" and removes "MIMIC2" from the PageLast
stack. */

PageLast();
! Displays page "MIMIC1".

PagePopUp
Description Display pop up window at the mouse position. If the mouse position is not known then the pop
up will display in the centre of the screen. The window is displayed with no resize and will be
closed if the page is changed.
Syntax PagePopUp(sPage)

sPage ...............The name of the page (drawn with the Graphics Builder).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageLast
Examples
458 PagePrev

PagePrev
Description Displays the previous page as specified in the project.
You cannot call this function from the Exit command field (see Page Properties) or a Cicode
Object.
Syntax PagePrev()

Return Value 0 (zero) if the page is successfully displayed, otherwise an error is returned.
Related Functions PageNext
Examples

Buttons
Text Page Previous

Command PagePrev()

Comment Display the previous page in the browse

sequence

System Keyboard
Key Sequence PagePrev

Command PagePrev()

Comment Display the previous page in the browse

sequence

/* If graphics page 10 is currently displayed, and graphics page 10 has

Prev Page Name=1. */
PagePrev();
! Displays graphics page 1.
 PagePushLast 459

PagePushLast
Description Places a page at the end of the PageLast stack.
Syntax PagePushLast(Page)

Page.................The Page Name or Page Number (of the page) to place at the end of the PageLast
stack.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PagePopLast, PagePeekLast
Examples
PageDisplay("MIMIC1");
! Displays page "MIMIC1".

PageDisplay("MIMIC2");
/* Displays page "MIMIC2" and places page "MIMIC1" onto the PageLast
stack. */

PageDisplay("10");
! Displays page "10" and places page "MIMIC2" onto the PageLast stack.

PagePushLast("TREND1");
! Places page "TREND1" onto the PageLast stack.

PageLast();
/* Displays the last page on the stack, i.e. page "TREND1" and removes
it from the stack. */

PageLast();
/* Displays the last page on the stack, i.e. page "MIMIC2" and removes
it from the stack. */

PageRichTextFile
Description This function creates a rich edit object, and loads a copy of the rich text file Filename into that
object. The rich text object will be rectangular in shape, with dimensions determined by
nHeight, and nWidth. If you do not specify nHeight and nWidth, hAn will define the position of
one corner, and (hAn + 1) the position of the diagonally opposite corner. This function would
often be used as a page entry function.
Syntax PageRichTextFile(hAn, Filename, nMode, nHeight, nWidth)

hAn ..................The animation point at which to display the rich text object.
460 PageRichTextFile

Filename .........The name of the file to be copied and loaded into the rich text object. The
filename must be entered in quotation marks "".

If you are loading a copy of an RTF report, the report must have already been
run and saved to a file. Remember that the filename for the saved report comes
from the File Name field in the Devices form. The location of the saved file
must also be included as part of the filename. For example, if the filename in the
Devices form listed [Data];RepDev.rtf, then you would need to enter
"[Data]\repdev.rtf" as your argument. Alternatively, you can manually enter
the path, e.g. "c:\citect\data\repdev.rtf".
If you are keeping a number of history files for the report, instead of using the rtf
extension, you must change it to reflect the number of the desired history file,
e.g. 001.

nMode .............The display mode for the rich text object. The mode can be any combination of:

0 ..... Disabled - should be used if the rich text object is to be used for display
purposes only.
1 ..... Enabled - allows you to select and copy the contents of the RTF object (for
instance an RTF report), but you will not be able to make changes.
2 ..... Read/Write - allows you to edit the contents of the RTF object. Remember,
however, that the object must be enabled before it can be edited. If it has
already been enabled, you can just enter Mode 2 as your argument. If it is
not already enabled, you will need to enable it. By combining Mode 1 and
Mode 2 in your argument (3), you can enable the object, and make it
read/write at the same time.

NOTE: .......Because the content of the rich text object is just a copy of the
original file, changes will not affect the actual file, until saved using
the DspRichTextSave function.

nHeight............The height of the rich text object in pixels. The height is established by
measuring down from the animation point.

NOTE: .......If you do not enter a height and width, the size of the object will be
determined by the position of hAn and h(An+1).

nWidth .............The width of the rich text object in pixels. The width is established by measuring
across to the right of the animation point.

NOTE: .......If you do not enter a height and width, the size of the object will be
determined by the position of hAn and h(An+1).

Return Value None

 PageRichTextFile 461

Related Functions DspRichText, DspRichTextLoad, DspRichTextEdit, DspRichTextEnable, DspRichTextGetInfo,

DspRichTextPgScroll, DspRichTextPrint, DspRichTextSave, DspRichTextScroll,
FileRichTextPrint
Examples
PageRichTextFile(108,"f:\citect\data\richtext.rtf",0);
// This function would produce a rich text object at animation point
108. Into this object a copy of f:\citect\data\richtext.rtf would then
be loaded. Remember, richtext.rtf is the name of the output file for the
report, as specified in the Devices form.
Because 0 was specified as the nMode for this example, the contents of
this object will be display only.
//

PageRichTextFile(53,"[Data]\richtext.rtf",1);
//This function would produce a rich text object at animation point 53.
Into this object a copy of [Data]\richtext.rtf would then be loaded. It
will be possible to select and copy the contents of the object, but not
make changes.
//

PageSelect
Description Displays a dialog box with a list of all graphics pages defined in the project. An operator can
select a page name for display.
Syntax PageSelect()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageGoto, PageLast, PagePrev, PageMenu
Examples

Buttons
Text Page Select

Command PageSelect()

Comment Display the page selection dialog box

PageSelect();
! Displays the page selection dialog box.
462 PageSetInt

PageSetInt
Description Stores a local page-based integer. Page-based variables are stored in an array, local to each
display page. This function allows you to save integer variables in temporary storage.
NOTE: You can dynamically change the setting for [Page]ScanTime parameter, by calling this
function as follows: PageSetInt(-2, <scantime>)
Syntax PageSetInt(Offset, Int)

Offset ............... The offset in the array of integers.

Int ....................The integer value to store.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageGetInt, PageGetStr, PageSetStr
Examples

PageSetStr
Description Stores a local page-based string. Page-based variables are stored in an array, local to each
display page. This function allows you to save string variables in temporary storage.
Specify the position of the variable in the array in the Offset argument. (The length of the array
is set by the [Page]MaxStr parameter.)
Syntax PageSetStr(Offset, String)

Offset ............... The offset in the array of strings.

String...............The string to store.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageGetInt, PageGetStr, PageSetInt
Examples

PageSummary
Description Displays a category of alarm summary entries on the alarm page. To use this function, you must
use the Graphics Builder to create a page called "Summary" (using the alarm template).
 PageSummary 463

NOTE: The operation of this function has changed. In Version 2.xx this function displayed the
in-built summary alarm page from the Include project.
Syntax PageSummary(Category)

Category ..........The alarm category to display. Set to 0 (the default) to display all alarm
categories.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageAlarm
Examples

System Keyboard
Key Sequence SummaryPage

Command PageSummary(0)

Comment Display all alarm summary entries on the

alarm page

System Keyboard
Key Sequence Summary ### Enter

Command PageSummary(Arg1)

Comment Display a specified category of alarm

summary entries on the alarm page

PageTrend
Description Displays a trend page with the specified trend pens. With this function you can display all the
trends in the system with a single trend page. You must create the trend page with the Graphics
Builder, and set all the pen names to blank. You then display that page by calling this function
and passing the required trend tags. You should call this function from a menu of trend pages.
Syntax PageTrend(sPage, sTag1 ... sTag8)

sPage ...............The name of the trend page (drawn with the Graphics Builder).
464 PageTrend

sTag1 ... sTag8 The trend tags to display on the page.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnNew, TrnSelect, TrendWin, TrendPopUp
Examples

Buttons
Text Process Trend

Command PageTrend("MyTrend", "PV1", "PV2",

"PV3")

Comment Display the trend page with three trend

pens

PageTrend("MyTrend", "PV1", "PV2", "PV3")

/* Display three trend tags on a single trend page. */

ParameterGet
Description Gets the value of a system parameter. The system parameter can exist in the CITECT.INI file
and/or in the Parameters database.
If the system parameter does not exist in the CITECT.INI file or the database, the default value is
returned. If the system parameter exists in both CITECT.INI and the database, the value of the
system parameter is taken from CITECT.INI.
Syntax ParameterGet(Section, Name, Default)

Section.............The section name.

Name ............... The system parameter name.

Default.............The default value of the parameter.

Return Value The parameter (as a string).

Related Functions ParameterPut, WndGetFileProfile, WndPutFileProfile,
Examples
Variable=ParameterGet("Page","Windows","4");
 ParameterGet 465

/* Sets Variable to 4 if the [Page] Windows system parameter does not

exist in CITECT.INI and the [Parameters] database, otherwise its value
is returned from wherever it was found. */

ParameterPut
Description Updates a system parameter in the CITECT.INI file. If the system parameter does not exist, it is
added to the CITECT.INI file.
Syntax ParameterPut(Section, Name, Value)

Section .............The section name.

Name................The system parameter name.

Value................The value to put in the system parameter.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ParameterGet, WndGetFileProfile, WndPutFileProfile,
Examples
/* Changes the [Page] Windows system parameter in CITECT.INI to "4". */
ParameterPut("Page","Windows","4");

PathToStr
Description Converts a Citect path into a string. The path string can contain one of the standard Citect path
operators, BIN, DATA, RUN, or a user-configured path. If the string does not contain a Citect
path, it is unchanged.
Syntax PathToStr(sPath)

sPath................The Citect path to convert.

Return Value A string containing the converted path.

Examples
Variable=PathToStr("[data]:test.txt");
! Sets Variable to "c:\citect\data\test.txt".
! assuming that DATA=C:\CITECT\DATA
466 Pi

Pi
Description Gets the value of pi (the ratio of the circumference of a circle to its diameter).
Syntax Pi()

Return Value The value of pi.

Examples
Variable=Pi();
! Sets Variable to 3.1415...

PlotClose
Description Displays the plot on the screen or sends it to the printer (depending on the output device you
specified in the PlotOpen() function), then closes the plot. Once the plot is closed, it cannot be
used.
Syntax PlotClose(hPlot)

hPlot................ The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotDraw, PlotGrid, PlotInfo, PlotLine, PlotMarker, PlotOpen, PlotScaleMarker, PlotText,
PlotXYLine, TrnPlot
Examples See PlotOpen.

PlotDraw
Description Constructs drawings on your plot. Use the coordinates (X1,Y1) and (X2,Y2) to define a point,
line, rectangle, square, circle, or ellipse. You can specify the style, colour, and width of the pen,
and a fill colour for a box or circular shape.
You must call the PlotOpen() function first, to get the handle for the plot (hPlot) and to specify
the output device.
Syntax PlotDraw(hPlot, Type, PenStyle, PenCol, PenWidth, nFill, X1, Y1, X2, Y2)

hPlot................ The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

Type.................The type of drawing:

 PlotDraw 467

1 ..... Rectangle or square

2 ..... Circle or ellipse
3 ..... Line
4 ..... Point

PenStyle...........The style of the pen used to draw:

0 ..... Solid
1 ..... Dash (- - - - -)
2 ..... Dot (...............................)
3 ..... Dash and dot (- . - . - . - . -)
4 ..... Dash, dot, dot ( - . . - . . - . . - )
5 .... Hollow

PenCol.............The colour of the pen. Refer to Colour Names and Codes for a list of colours.

PenWidth .........The width of the pen, in pixels. If the width is thicker than one pixel, you must
use a solid pen (PenStyle = 0). The maximum width is 32.

nFill .................The fill colour of the rectangle, square, circle, or ellipse. Refer to Colour Names
and Codes for a list of colours. For a point or line, nFill is ignored.

X1, Y1, X2, Y2..X1, Y1 The x and y coordinates (in pixels) of the upper left corner of the
drawing - the origin.

X2, Y2 The x and y coordinates (in pixels) of the lower right corner of the
drawing.
For a point, (X1,Y1) and (X2,Y2) are assumed to be the same, so (X2,Y2) is
ignored. To draw a circle or ellipse, enter the coordinates for a square or
rectangle - the circle or ellipse is automatically drawn within the box.
If the plot is for display on the screen, all coordinates are relative to the AN
specified in the PlotOpen() function. If the output device is a printer, all
coordinates are relative to the point (0,0).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotClose, PlotGrid, PlotInfo, PlotLine, PlotMarker, PlotOpen, PlotScaleMarker, PlotText,
PlotXYLine, TrnPlot
Examples See PlotOpen.
468 PlotGetMarker

PlotGetMarker
Description Gets the marker number of a symbol. The symbol must be a symbol and registered with the
PlotSetMarker() function.
Syntax PlotGetMarker(sSymbolName)

sSymbolName .. The name and path of the symbol to be defined as a marker.

Return Value The marker number if successful, otherwise -1 is returned.

Related Functions PlotMarker, PlotScaleMarker, PlotSetMarker
Examples
/*Assume that the symbol was registered by PlotSetMarker function */
PlotSetMarker(20,"Global.Hourglass");
/*Later on, this symbol can be used as shown below*/
hPlot = PlotOpen(36,"Display",1);
:
/* Display red hourglass as marker at point (100,200) on AN36. */
MarkerNo = PlotGetMarker("Global.Hourglass");
PlotMarker(hPlot,MarkerNo,red,1,1,100,200);
:
PlotClose(hPlot);

PlotGrid
Description Defines a frame and draws horizontal and vertical grid lines within this frame. These grid lines
can then be used by the PlotLine(), PlotXYLine(), and PlotScaleMarker() functions. You must
define the frame for a plot before you can plot points with the PlotLine() and PlotXYLine()
functions. nSamples specifies the maximum number of samples that can be plotted for a single
line. If you set FrameWidth to 0 (zero), the frame will be defined but not displayed (however,
the plot will still be displayed).
You can specify the number of grid lines and their colour, as well as the background colour
which will fill the frame. If nHorGrid and nVerGrid are set to 0 (zero), then the grid lines will
not be drawn.
You must call the PlotOpen() function, first, to get the handle for the plot (hPlot), and to specify
the output device. Then call this function to set up the frame and grid. You can then call the
PlotScaleMarker() function to draw scale lines beside the frame, and call the PlotLine() or
PlotXYLine() to plot a set of data points.
Syntax PlotGrid(hPlot, nSamples, X1, Y1, X2, Y2, nHorGrid, HorGridCol, nVerGrid, VerGridCol,
FrameWidth, FrameCol, nFill, nMode)
 PlotGrid 469

hPlot ................The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

nSamples..........The maximum number of samples that can be plotted for a single line in this
grid. For example, if you set nSamples to 10, then plot 2 lines in this grid (using
the PlotLine() function), each line will be plotted with a maximum of 10
samples. For this example, a line can possess less than 10 samples, but if it has
more, it will be shortened to 10 samples.

X1, Y1, X2, Y2..X1, Y1 The x and y coordinates of the upper left corner of the frame
containing the grid lines.

X2, Y2 The x and y coordinates of the lower right corner of the frame
containing the grid lines.
If the plot is for display on the screen, you should set (X1,Y1) to (0,0). The
origin of the frame is then positioned at the AN specified in the PlotOpen()
function.
If the output device is a printer, both (X1,Y1) and (X2,Y2) are relative to the
point (0,0).

nHorGrid .........The number of rows (formed by the horizontal grid lines) to draw within the
frame. If you do not need grid lines, set nHorGrid to 0 (zero) and HorGridCol
to 0.

HorGridCol .....The colour of the horizontal grid lines. Refer to Colour Names and Codes for a
list of colours.

nVerGrid..........The number of columns (formed by the vertical grid lines) to draw within the
frame. If you do not need grid lines, set nVerGrid to 0 (zero) and VerGridCol to
0.

VerGridCol......The colour of the vertical grid lines. Refer to Colour Names and Codes for a list
of colours.

FrameWidth.....The width (also called pen width) of the frame enclosing the grid, in pixels. To
define the frame without drawing its boundaries, set FrameWidth to 0 (zero) and
FrameCol to 0. The maximum is 32.

FrameCol ........The colour of the frame enclosing the grid. Refer to Colour Names and Codes
for a list of colours.

nFill .................The background colour for the frame. Refer to Colour Names and Codes for a
list of colours.

nMode..............The mode of the plot. For future use only - set to 0 (zero).
470 PlotGrid

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotClose, PlotDraw, PlotInfo, PlotLine, PlotMarker, PlotOpen, PlotScaleMarker, PlotText,
PlotXYLine, TrnPlot
Examples See PlotOpen.

PlotInfo
Description Gets information about the plot. You can call this function to determine the number of pixels per
page or inch, the resolution of a plot, and the size and spacing of characters for a specified text
font. You can also check whether a printer can print rotated text. (See PlotText().)
You must first call the PlotOpen() function to get the handle for the plot (hPlot) and specify the
output device.
Syntax PlotInfo(hPlot, Type, sInput)

hPlot................ The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

Type.................The type of plot information to get:

0 ..... Horizontal pixels on a printout page

1 ..... Vertical pixels on a printout page
2 ..... Horizontal pixels per inch
3 ..... Vertical pixels per inch
4 ..... Horizontal resolution
5 ..... Vertical resolution
6 ..... Height of the font used
7 ..... External leading of the font used
8 ..... Character width of the font used
9 ..... Rotatable text is allowed or not
10 ... Indicates whether or not a font is supported
11 ... Horizontal size of a page in millimetres
12 ... Vertical size of a page in millimetres

sInput...............The font handle (hFont), returned from the DspFont() function. . Useful only
for Type 6, 7, 8, or 10.
 PlotInfo 471

Return Value The attributes of the plot as a string.

Related Functions PlotClose, PlotDraw, PlotGrid, PlotLine, PlotMarker, PlotOpen, PlotScaleMarker, PlotText,
PlotXYLine, TrnPlot
Examples
hPlot = PlotOpen(36,"Display",1);
:
/* Print text in upward direction but first check if printer supports
text rotation. Set default text orientation to left to right (just in
case). */
Orient = 0;
IF PlotInfo(hPlot,9) THEN
Orient = 1;
END
PlotText(hPlot,hFont,Orient,100,100,"scale");
:
/* Print text "Citect Graph" centred horizontally at top of page. */
PageWidth = PlotInfo(hPlot,0) ; ! Get width of page
hFont = DspFont("Courier",14,black,-1);
TextWidth = PlotInfo(hPlot,8,hFont); ! Get width of each character
TextPosn = (PageWidth - TextWidth * 12) / 2 ! Get start of 1st
character
PlotText(hPlot,hFont,0,TextPosn,0,"Citect Graph");
:
PlotClose(hPlot);

PlotLine
Description Draws a line (in the Citect plot system) for a set of data points. You specify the data points in
the table pTable, and plot these points between the LoScale and HiScale values. The line is
drawn inside the frame defined by the PlotGrid() function.
For each line on a plot, you can specify a different pen style, colour, and width, and a different
marker style and colour. You can draw lines either from left to right or from right to left.
You must first call the PlotOpen() function to get the handle for the plot (hPlot) and specify the
output device. You should then use the PlotGrid() function to set up the frame and grid, before
you call this function to plot the line.
Syntax PlotLine(hPlot, PenStyle, PenCol, PenWidth, MarkerStyle, MarkerCol, nMarker, Length,
pTable, LoScale, HiScale, Mode)

hPlot ................The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

PenStyle...........The style of the pen used to draw:

472 PlotLine

0 ..... Solid
1 ..... Dash (- - - - -)
2 ..... Dot (...............................)
3 ..... Dash and dot (- . - . - . - . -)
4 ..... Dash, dot, dot ( - . . - . . - . . - )
5 .... Hollow

PenCol.............The colour of the pen. Refer to Colour Names and Codes for a list of colours.

PenWidth.........The width of the pen, in pixels. If the width is thicker than one pixel, you must
use a solid pen (PenStyle = 0). The maximum width is 32.

MarkerStyle.....The style of the markers:

0 ..... No markers
1 ..... Triangle
2 ..... Square
3 ..... Circle
4 ..... Diamond
5 .... Filled triangle
6 .... Filled square
7 ..... Filled circle
8 .... Filled diamond
20 - 32000 ..User-defined markers. You can register any symbol as a marker
with the PlotSetMarker() function. Call the PlotGetMarker()
function if you do not know the number of a marker you have
previously registered.

MarkerCol.......The colour of the markers. Refer to Colour Names and Codes for a list of
colours.

nMarker...........The number of samples between markers.

Length .............The length of the array, i.e. the number of points in the table pTable for
PlotLine(), or in tables xTable and yTable for PlotXYLine().

For every line you draw with the PlotLine() and PlotXYLine() functions within a
plot, you must add the Length arguments for each call, and pass the total to the
PlotGrid() function (in the nSamples argument).
 PlotLine 473

pTable..............The points to be plotted (as an array of floating-point values).

LoScale ............The lowest value that will be displayed on the plot (i.e. the value assigned to the
origin of your grid). The LoScale and HiScale values determine the scale of
your grid. This scale is used to plot values. e.g. If LoScale = 0 (zero) and
HiScale = 100, a value of 50 will be plotted half way up the Y-axis of your grid.

LoScale must be in the same units as the values in pTable.

HiScale ............The highest value that will be displayed on the plot. The LoScale and HiScale
values determine the scale of your grid. This scale is used to plot values. e.g. If
LoScale = 0 (zero) and HiScale = 100, a value of 50 will be plotted half way up
the Y-axis of your grid.

HiScale must be in the same units as the values in pTable.

Mode................The origin of your grid, and the direction of the plotted line:

1 ..... Origin is bottom-left, x is left to right, y is upwards

2 .... Origin is bottom-right, x is right to left, y is upwards
4 .... Origin is top-left, x is left to right, y is downwards
8 .... Origin is top-right, x is right to left, y is downwards

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotClose, PlotDraw, PlotGetMarker, PlotGrid, PlotInfo, PlotMarker, PlotOpen,
PlotScaleMarker, PlotSetMarker, PlotText, PlotXYLine, TrnPlot
Examples See PlotOpen.

PlotMarker
Description Draws markers on a plotted line or at a specified point. You can plot any one of the standard
markers, or use a symbol of your choice. (You must first register your symbol as a marker, by
using the PlotSetMarker() function.)
To draw a single marker at a specified point, set X and Y to the coordinates of the point, and set
Length to 1.
You can draw markers on a plotted line when you draw the line, i.e. within the PlotLine() or
PlotXYLine() function. You would use the PlotMarker() function only if you need to draw a
second set of markers on the same line. Call PlotMarker() immediately after the line is drawn.
Set X and Y to -1 and Length to the number of data points (specified in the Length argument of
the PlotLine() or PlotXYLine() function).
474 PlotMarker

You must first call the PlotOpen() function to get the handle for the plot (hPlot) and specify the
output device.
Syntax PlotMarker(hPlot, MarkerStyle, MarkerCol, nMarker, Length, X, Y)

hPlot................ The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

MarkerStyle.....The style of the markers:

0 ..... No markers
1 ..... Triangle
2 ..... Square
3 ..... Circle
4 ..... Diamond
5 .... Filled triangle
6 .... Filled square
7 ..... Filled circle
8 .... Filled diamond
20 - 32000 ..User-defined markers. You can register any symbol as a marker
with the PlotSetMarker() function. Call the PlotGetMarker()
function if you do not know the number of a marker you have
previously registered.

MarkerCol.......The colour of the markers. Refer to Colour Names and Codes for a list of
colours.

nMarker...........The number of samples between markers.

Length .............The length of the array (the number of line points in the table pTable) plotted in
the PlotLine() or PlotXYLine() function. To draw only one marker at a specified
point, set Length to 1.

X ......................The x and y coordinates, in pixels, of the point where the marker is to be drawn.
If the plot is for display on the screen, the coordinates are relative to the AN
specified in the PlotOpen() function. If the output device is a printer, the
coordinates are relative to the point (0,0).

To draw the markers on a plotted line, set both X and Y to -1, and set Length to
the same value as the Length passed in the PlotLine() or PlotXYLine() function.
 PlotMarker 475

Y.......................The x and y coordinates, in pixels, of the point where the marker is to be drawn.
If the plot is for display on the screen, the coordinates are relative to the AN
specified in the PlotOpen() function. If the output device is a printer, the
coordinates are relative to the point (0,0).

To draw the markers on a plotted line, set both X and Y to -1, and set Length to
the same value as the Length passed in the PlotLine() or PlotXYLine() function.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotClose, PlotDraw, PlotGetMarker, PlotGrid, PlotInfo, PlotLine, PlotOpen, PlotScaleMarker,
PlotSetMarker, PlotText, PlotXYLine, TrnPlot
Examples
hPlot=PlotOpen(36,"Display",1);
:
/* Draw a filled red square marker at the point (X=100,Y=200). */
PlotMarker(hPlot,6,red,1,1,100,200);
:
/* Draw 10 black triangles and 5 green cylinders along a plot line. */
PlotLine(hPlot,0,black,3,5,black,10,100,Buf2[0],0,100,2);
PlotSetMarker(20,"Global.Cylinder");
PlotMarker(hPlot,20,green,5,100,-1,-1)
:
PlotClose(hPlot);

PlotOpen
Description Opens a new plot, sets its output device, and returns its plot handle. You can send the plot to any
one of your system printers, or display it on the screen at the specified AN.
You must call this function before you can call the other plot functions.
Syntax PlotOpen(hAn, sOutput, Mode)

hAn ..................The animation point (AN) where the plot will display. Set the AN to 0 (zero)
when sOutput is a printer.

sOutput ............The output device where the plot is sent, for example:

"Display" Display on the screen. The plot is recorded in a metafile and

displayed (at the specified hAn) when the plot system is closed.
"LPT1:" Send to printer LPT1:
"LPT2:" Send to printer LPT2:
(and so on for any output device)
476 PlotOpen

Mode ...............When a plot is removed or updated, the portion of the background screen
beneath it is blanked out. The mode determines how the background screen is
restored.

The mode of the plot system:

1 ..... Normal mode
2 ..... Use for compatibility with the old graph functions
17 ... Soft (valid for normal mode). The background screen (a rectangular region
beneath the plot) is restored with the original image. Any objects that are
within the rectangular region are destroyed when the background is
restored.
33 ... Hard (valid for normal mode). The background screen (a rectangular
region beneath the plot) is painted with the colour at the AN.
65 ... Permanent (valid for normal mode). The plot is not erased. As the plot is
updated, it is re-displayed on top. This mode provides fast updates.
Transparent colour is supported in this mode.
129 .............Opaque animation (valid for normal mode). The plot is not erased.
As the plot is updated, it is re-displayed on top. This mode provides
the fastest updates. Transparent colour is not supported in this
mode.
257 .............Overlapped animation (valid for normal mode). The background
screen (the rectangular region beneath the plot) is completely
repainted.

Return Value The plot handle if the plot is opened successfully, otherwise -1 is returned. The plot handle
identifies the table where all data on the associated plot is stored.
Related Functions PlotClose, PlotDraw, PlotGrid, PlotInfo, PlotLine, PlotMarker, PlotScaleMarker, PlotText,
PlotXYLine, TrnPlot
Examples
hPlot=PlotOpen(0,"LPT2:",1);
IF hPlot <> -1 THEN
/* Set up a black frame with red & blue grid lines. */
PlotGrid(hPlot,18,450,800,1850,1600,5,red,10,blue,4,black,white,0);

/* Draw a scale line to the left of the frame. */

PlotScaleMarker(hPlot,400,1600,6,1,black,0);

/* Plot a simple line in green for a table of 10 values. */

PlotLine(hPlot,0,green,3,6,green,2,10,Buf1,0,100,1);

/* Plot a line in yellow (with black markers) for tables of 8 X and Y

values. */
 PlotOpen 477

PlotXYLine(hPlot,0,yellow,4,3,black,2,8,Buf2,0,150,Buf3,0,100,1);

/* Draw a title box above the plot frame, with the heading "Citect
Graph". */
PlotDraw(hPlot,1,0,black,1,grey,900,250,1400,400);
hFont = DspFont("Times",-60,black,grey);
PlotText(hPlot,hFont,0,950,350,"Citect Graph");

PlotClose(hPlot);
END
The above example prints the following (on the printer):

Frame and gridlines drawn Box drawn with the

with the PlotGrid() function PlotDraw() function

Citect Graph Text drawn with the

PlotText() function

Scale Marker drawn with the Line drawn with the

PlotScaleMarker() function PlotLine() function
Line drawn with the
PlotXYLine() function

PlotOpen(0,"LPT1:",1) // opens a new plot to be sent to printer

PlotOpen(20,"DISPLAY",17) // normal plot with soft animation
PlotOpen(20,"DISPLAY",257) // normal plot with overlap animation
PlotOpen(20,"DISPLAY",1) // normal plot with overlap animation(for
default animation mode is overlap animation)
PlotOpen(20,"DISPLAY",16) // INVALID (does not specify whether it is
normal or Version 2.xx mode).
PlotOpen(20,"DISPLAY",2) // INVALID for Version 2.xx graph system (does
not support display as output).
478 PlotScaleMarker

PlotScaleMarker
Description Draws scale lines beside the grid on your plot (if there is one) and places markers on them. The
height of the scale line is automatically set to the height of the frame set in the PlotGrid()
function.
You must first call the PlotOpen() function to get the handle for the plot (hPlot) and specify the
output device. You should then use the PlotGrid() function to set up the frame and grid, before
you call this function to draw the scale lines.
Syntax PlotScaleMarker(hPlot, X, Y, nMarker, PenWidth, PenCol, Mode)

hPlot................ The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

X ......................The x and y coordinates of the point where the scale line starts. The end
coordinates of the scale line are automatically defined by the size of the frame
(set in the PlotGrid() function).

If the plot is for display on the screen, all coordinates are relative to the AN
specified in the PlotOpen() function. If the output device is a printer, all
coordinates are relative to the point (0,0).

Y ......................The x and y coordinates of the point where the scale line starts. The end
coordinates of the scale line are automatically defined by the size of the frame
(set in the PlotGrid() function).

If the plot is for display on the screen, all coordinates are relative to the AN
specified in the PlotOpen() function. If the output device is a printer, all
coordinates are relative to the point (0,0).

nMarker...........The number of markers on the scale line.

PenWidth.........The width of the scale line, in pixels.

PenCol.............The colour of the pen. Refer to Colour Names and Codes for a list of colours.

Mode ...............The mode of the markers:

0 .... Both sides of the scale line

1 .... Left of the scale line
2 .... Right of the scale line

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotClose, PlotDraw, PlotGetMarker, PlotGrid, PlotInfo, PlotLine, PlotMarker, PlotOpen,
PlotSetMarker, PlotText, PlotXYLine, TrnPlot
 PlotScaleMarker 479

Examples See PlotOpen.

PlotSetMarker
Description Registers a symbol as a marker You can then draw the new marker at points and on plotted
lines, by specifying the MarkerNo of the symbol as the MarkerStyle in the PlotMarker()
function. Call the PlotGetMarker() function if you do not know the number of a marker.
Syntax PlotSetMarker(MarkerNo, sSymbolName)

MarkerNo ........The number of the marker, to be used as the MarkerStyle in the PlotMarker()
function. Your marker numbers must be greater than or equal to 20 (to a
maximum of 32000).

sSymbolName ..The name and path of the symbol to be defined as a marker.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotGetMarker, PlotMarker
Examples
hPlot=PlotOpen(30,"Display",1);
:
/* Display red hourglass as marker at point (100,200). */
PlotSetMarker(20,"Global.Hourglass");
PlotMarker(hPlot,20,red,1,1,100,200);
:
PlotClose(hPlot);

PlotText
Description Prints text on a plot. You can specify the font, position, and orientation of the text. If you
specify an orientation other than 'left-to-right', you must check that the font (and the printer)
supports the orientation.
You must first call the PlotOpen() function to get the handle for the plot (hPlot) and specify the
output device. You also must call the DspFont() function to get a handle for the font (hFont).
Syntax PlotText(hPlot, hFont, Orientation, X, Y, sText)

hPlot ................The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.
480 PlotText

hFont ...............The font handle, returned from the DspFont() function. The font handle
identifies the table where details of that font are stored.

Orientation ......The orientation of the text:

0 .... Left-to-right
1 .... Upwards
2 .... Right-to-left
3 .... Downwards
You should check that the font supports rotation (where Orientation = 1, 2, or 3).
Most true type and vector fonts support rotation. If the PlotInfo(hPlot, 9)
function returns false, you must specify an Orientation of 0 (zero).

X ......................The x and y coordinates (in pixels) of the start of the text. If the plot is for
display on the screen, the coordinates are relative to the AN specified in the
PlotOpen() function. If the output device is a printer, the coordinates are relative
to the point (0,0).

Y ......................The x and y coordinates (in pixels) of the start of the text. If the plot is for
display on the screen, the coordinates are relative to the AN specified in the
PlotOpen() function. If the output device is a printer, the coordinates are relative
to the point (0,0).

sText ................ The text string to be plotted.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspFont, PlotClose, PlotDraw, PlotGrid, PlotInfo, PlotLine, PlotMarker, PlotOpen,
PlotScaleMarker, PlotXYLine, TrnPlot
Examples See PlotOpen().

PlotXYLine
Description Plots values from two different tables. Values from one table are considered X coordinates, and
values from the other are considered Y coordinates. Points are plotted between the low and high
scale values specified for x and y. The line is plotted inside the frame defined by the PlotGrid()
function.
For each line, you can specify a different pen style, colour, and width, and a different marker
style and colour. You can draw lines either from left to right or from right to left.
 PlotXYLine 481

You must first call the PlotOpen() function to get the handle for the plot (hPlot) and specify the
output device. You should then use the PlotGrid() function to set up the frame and grid, before
you call this function to plot the line.
Syntax PlotXYLine(hPlot, PenStyle, PenCol, PenWidth, MarkerStyle, MarkerCol, nMarker, Length,
XTable, LoXScale, HiXScale, YTable, LoYScale, HiYScale, Mode)

hPlot ................The plot handle, returned from the PlotOpen() function. The plot handle
identifies the table where all data on the plot is stored.

PenStyle...........The style of the pen used to draw:

0 ..... Solid
1 ..... Dash (- - - - -)
2 ..... Dot (...............................)
3 ..... Dash and dot (- . - . - . - . -)
4 ..... Dash, dot, dot ( - . . - . . - . . - )
5 .... Hollow

PenCol.............The colour of the pen. Refer to Colour Names and Codes for a list of colours.

PenWidth .........The width of the pen, in pixels. If the width is thicker than one pixel, you must
use a solid pen (PenStyle = 0). The maximum width is 32.

MarkerStyle .....The style of the markers:

0 ..... No markers
1 ..... Triangle
2 ..... Square
3 ..... Circle
4 ..... Diamond
5 .... Filled triangle
6 .... Filled square
7 ..... Filled circle
8 .... Filled diamond
20 - 32000 . User-defined markers. You can register any symbol as a marker
with the PlotSetMarker() function. Call the PlotGetMarker()
function if you do not know the number of a marker you have
previously registered.
482 PlotXYLine

MarkerCol.......The colour of the markers. Refer to Colour Names and Codes for a list of
colours.

nMarker...........The number of samples between markers.

Length .............The length of the array, i.e. the number of points in the table pTable for
PlotLine(), or in tables xTable and yTable for PlotXYLine().

For every line you draw with the PlotLine() and PlotXYLine() functions within a
plot, you must add the Length arguments for each call, and pass the total to the
PlotGrid() function (in the nSamples argument).

XTable .............The x coordinates for the points in the line, as an array of floating point values.

LoXScale ......... The lowest X-axis value that will be displayed on the plot (i.e. the X-coordinate
of the origin of your grid). The LoXScale and HiXScale values determine the
scale of your grid. This scale is used to plot values. e.g. If LoXScale = 0 (zero)
and HiXScale = 100, a value of 50 will be plotted half way along the X-axis of
your grid.

LoXScale must be in the same units as the values in xTable.

HiXScale ......... The highest X-axis value that will be displayed on the plot. The LoXScale and
HiXScale values determine the scale of your grid. This scale is used to plot
values. e.g. If LoXScale = 0 (zero) and HiXScale = 100, a value of 50 will be
plotted half way along the X-axis of your grid.

HiXScale must be in the same units as the values in xTable.

YTable .............The y coordinates for the points in the line, as an array of floating point values.

LoYScale ......... The lowest Y-axis value that will be displayed on the plot (i.e. the Y-coordinate
of the origin of your grid). The LoYScale and HiYScale values determine the
scale of your grid. This scale is used to plot values. e.g. If LoYScale = 0 (zero)
and HiYScale = 100, a value of 50 will be plotted half way up the Y-axis of your
grid.

LoYScale must be in the same units as the values in xTable.

HiYScale.......... The highest Y-axis value that will be displayed on the plot. The LoYScale and
HiYScale values determine the scale of your grid. This scale is used to plot
values. e.g. If LoYScale = 0 (zero) and HiYScale = 100, a value of 50 will be
plotted half way up the Y-axis of your grid.

HiYScale must be in the same units as the values in xTable.

Mode ...............The origin of your grid, and the direction of the plotted line:
 PlotXYLine 483

1 ..... Origin is bottom-left, x is left to right, y is upwards

2 .... Origin is bottom-right, x is right to left, y is upwards
4 .... Origin is top-left, x is left to right, y is downwards
8 .... Origin is top-right, x is right to left, y is downwards

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PlotClose, PlotDraw, PlotGetMarker, PlotGrid, PlotInfo, PlotLine, PlotMarker, PlotOpen,
PlotScaleMarker, PlotSetMarker, PlotText, TrnPlot
Examples See PlotOpen().

Pow
Description Calculates x to the power of y.
Syntax Pow(X, Y)

X, Y ..................X The base number.

Y.... The exponent.

Return Value X to the power of Y.

Related Functions Exp
Examples
Variable=Pow(5,3);
! Sets Variable to 125.

Print
Description Prints a string on the current device. You should call this function only in a report. The output
is sent to the device (or group of devices) defined in the Reports database (in the output device
field).
Syntax Print(String)

String ...............The string (data) to print.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PrintLn
484 Print

Examples
! Print "Testvar" and stay on the same line.
Print("Value of Testvar="+Testvar:##.#);

PrintFont
Description Changes the printing font on the current device. You should call this function only in a report. It
will change the font style for the device (or group of devices) defined in the Reports database
(output device field). It has effect only on reports being printed to a PRINTER_DEV - it has no
effect on other types of devices, such as ASCII_DEV and dBASE_DEV.
Syntax PrintFont(Font)

Font .................The Citect font (defined in the Fonts database).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Print
Examples
The following report file...

{! example.rpt }

-------------------------------------
An example Report
-------------------------------------

{CICODE}
PrintFont("HeadingFont");
{END}
Plant Area 1
{CICODE}
PrintFont("ReportFont");
{END}

{Time(1) } {Date(2) }
PV_1 {PV_1:#####.##}
PV_2 {PV_2:#####.##}

----------End of Report---------------

...will print as...

-------------------------------------
An example Report
-------------------------------------
 PrintFont 485

Plant Area 1

04:41:56 19-10-93
PV_1 49.00
PV_2 65.00

----------End of Report---------------

PrintLn
Description Prints a string on the current device, followed by a newline character. You should call this
function only in a report. The output will be sent to the device or group of devices defined in the
Reports database (in the output device field).
Syntax PrintLn(String)

String ...............The string (data) to print.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Print
Examples
! Print "Testvar" followed by a new line.
PrintLn("Value of Testvar="+Testvar:##.#);

ProjectRestartGet
Description Gets the path to the project to be run the next time Citect is restarted. (You must have a project
already set using either ProjectSet or ProjectRestartSet. Use this function with the Shutdown()
function to shut down the project that is currently running.
Syntax ProjectRestartGet()

Return Value The path to the project to be run the next time Citect is restarted.
Related Functions Shutdown, ShutdownMode, ProjectSet, ProjectRestartSet
Examples See Shutdown().
486 ProjectRestartSet

ProjectRestartSet
Description Sets the path to the project to be run the next time Citect is restarted.
Syntax ProjectRestartSet(sPath)

sPath ...............The path to the project. You must use the full path, for example to specify the
path to the project "Demo", use: "C:\CITECT\USER\DEMO".

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Shutdown, ShutdownMode, ProjectRestartGet
Examples

ProjectSet
Description Sets either the name or the path of the project to be run next time Citect is restarted. The project
path is written to the [CtEdit]Run parameter.
Syntax ProjectSet(sProject)

sProject ...........The name of the project (for example "DEMO"), or the path to the project. If
you specify the path to the project, you must use the full path, for example to
specify the path to the project "Demo", use: "C:\CITECT\USER\DEMO". If you
do not specify a project, the current project will be used.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Shutdown, ShutdownMode, ProjectRestartGet
Examples
/* Set the next project to "Demo". */
ProjectSet("Demo");
/* Set the next project to "MyPath". */
ProjectSet("I:\CITECT\PROJECT1\MYPATH");

Prompt
Description Displays a message in the prompt line on the operator's computer.
Syntax Prompt(String)

String...............The message to be displayed.

 Prompt 487

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Message, DspError
Examples
/* Display "This is a prompt!" at the prompt AN. */
Prompt("This is a prompt!");

Pulse
Description Pulses (jogs) a variable tag on, then off. The variable tag is switched ON (1) and two seconds
later it is switched OFF (0). The exact period of the pulse is determined by the communication
channel to the I/O Device. If the communication channel is busy, the pulse time may be longer
than two seconds. The code in the I/O Device should not rely on a pulse time of exactly 2
seconds. Use the pulse as a trigger only.
Syntax Pulse(sTag)

sTag .................The digital tag to pulse.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Toggle
Examples

Buttons
Text Jog 145
Command Pulse(M145)

Comment Pulse the variable tag M145 every two

seconds

QueClose
Description Closes a queue opened with the QueOpen() function. All data is flushed from the queue.
If a Cicode task is waiting on the QueRead() function, it returns with a "queue empty" status.
You should close all queues when they are no longer required, because they consume memory.
At shutdown, Citect closes all open queues.
488 QueClose

Syntax QueClose(hQue)

hQue................The queue handle, returned from the QueOpen() function. The queue handle
identifies the table where all data on the associated queue is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions QueLength, QueOpen, QueRead, QueWrite, QuePeek
Examples
hQue=QueOpen("MyQue",1);
.
.
QueClose(hQue);

QueLength
Description Gets the current length of the queue.
Syntax QueLength(hQue)

hQue................The queue handle, returned from the QueOpen() function. The queue handle
identifies the table where all data on the associated queue is stored.

Return Value The current length of the queue. If the queue is closed then 0 is returned.
Related Functions QueClose, QueOpen, QueRead, QueWrite, QuePeek
Examples
Length=QueLength(hQue);

QueOpen
Description Open a queue for reading and writing data elements. Use this function to create a new queue or
open an existing queue. Use queues for sending data from one task to another or for other
buffering operations.
Syntax QueOpen(Name, Mode)

Name ............... The name of the queue.

Mode ...............The mode of the queue open:

0 .... Open existing queue.

 QueOpen 489

1 .... Create new queue.

2 ..... Attempts to open an existing queue. If the queue does not exist, it will
create it.

Return Value The queue handle, or -1 if the queue cannot be opened. The queue handle identifies the table
where all data on the associated queue is stored.
Related Functions QueClose, QueLength, QueRead, QueWrite, QuePeek
Examples
! Create a queue.
hQue=QueOpen("MyQue",1);
! Write data into the queue.
QueWrite(hQue,1,"Quetext");
QueWrite(hQue,1,"Moretext");
! Read back data from the queue.
QueRead(hQue,Type,Str,0);

QuePeek
Description Searches a queue for a queue element. You can search for the element by specifying a string, an
integer, or both. You can remove the element from the queue by adding 8 to the Mode.

WARNING: This function may modify the arguments Type and Str depending on the Mode. Therefore,
these arguments must be variables. You should be careful to not assume that they have not been changed
when calling the function.

Syntax QuePeek(hQue, Type, Str, Mode)

hQue ................The queue handle, returned from the QueOpen() function. The queue handle
identifies the table where all data on the associated queue is stored.

Type .................The number to search for (if using the search mode for a matching number). If
you are using a matching string mode, the number found is returned in Type.

Str ....................The string to search for (if using the search mode for a matching string). If you
are using a matching number mode, the string found is returned in Str.

Mode................The mode of the search:

1 ..... Search for a matching string.

2 ..... Search for a matching number.
4 ..... Search for a matching string and use a case-sensitive search.
490 QuePeek

8 ..... If the element is found, remove it from the queue.

16 ... Search the queue, in order, for the element at the offset specified by Type.
You can extend the search by adding modes. For example, set Mode to 3 to
search for a matching string and matching number, or set Mode to 11 to also
remove the string and number from the queue.
Use mode 16 when you know the location of the element you want. For example
if you set Type = 0, QuePeek will return the first element in the queue, type = 2,
will return the 3rd element in the queue, etc. If you specify an offset which is
greater than the length of the queue, the "queue empty" error (296) is returned.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions QueClose, QueOpen, QueLength, QueRead, QueWrite
Examples
STRING Str;
INT Type;
! search for 'mystring' in queue, don't remove if found
Str = "mystring";
status=QuePeek(hQue,Type,Str,1);
IF Status = 0 THEN
! Now use found Type
.
END

QueRead
Description Reads data from a queue, starting from the head of the queue. Data is returned in the same order
as it was written onto the queue and is removed from the queue when read. If the Mode is 0
(non-blocking) and the queue is empty, the function returns with an error. If the Mode is 1
(blocking) the function does not return until another Cicode task writes data onto the queue.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax QueRead(hQue, Type, Str, Mode)

hQue................The queue handle, returned from the QueOpen() function. The queue handle
identifies the table where all data on the associated queue is stored.

Type.................The integer variable to read from the queue (written to the queue as Type by the
QueWrite() function).

Str....................The string variable to read from the queue (written to the queue as Str by the
QueWrite() function).
 QueRead 491

Mode................The mode of the read:

0 .... Non-blocking.
1 .... Wait for element.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions QueClose, QueLength, QueOpen, QueWrite, QuePeek
Examples
Status=QueRead(hQue,Type,Str,0);
IF Status = 0 THEN
! Now use Type and Str.
.
.
END

QueryFunction
Description The user-defined query function set in AlarmSetQuery(). This function is called for each alarm,
and determines whether the alarm should be displayed on the Alarms Page.
When filtering the alarms, you can examine the information in an alarm field by calling
AlarmGetFieldRec from within your query function.

NOTE: The function name "QueryFunction" can be any valid Cicode function name specified by the user.

Syntax QueryFunction(nRID, nVer, Arg 01, Arg 02)

nRID ................The record number of the alarm currently being filtered. This provides the query
function with access to information about the alarm.

This parameter is represented with an INT, and must be the first parameter of
your query function.

nVer ................The version of an alarm.

If an alarm is triggered more than once in a given period, the version lets you
distinguish between different instances of the alarm's activity.
Since you may wish to display on a page alarms which have more than one
instance, this parameter must be passed to AlarmGetFieldRec in order to
correctly filter the alarms.
The version is represented with an INT, and must be the second parameter of
your query function.
 492 QueryFunction

Arg 01, Arg 02. A list of arguments, separated by commas.

The query function is passed the arguments specified in the call to

AlarmSetQuery(). For this reason, the arguments listed in AlarmSetQuery() must
be of the same type as those defined in the query function.

Return Value The return value must be defined as an INT with a value of either TRUE or FALSE. If the
function returns a value of TRUE, the alarm being filtered is displayed, otherwise it is excluded
from the alarms list.
Related Functions AlarmSetQuery, AlarmGetFieldRec, AlarmSetInfo

Example
! The query function AlarmQueryDate() compares sDate with the OnDate of
each alarm.AlarmGetFieldRec() is used to check the contents of the
"OnDate" field for each alarm.
! If they are the same, the alarm is displayed.
INT
FUNCTION
AlarmQueryDate(INT nRID, INT nVer, STRING sDate)
INT bResult;

IF sDATE = AlarmGetFieldRec(nRID, "OnDate", nVer) THEN

bResult = TRUE;
ELSE
bResult = FALSE;
END

RETURN bResult;
END

QueWrite
Description Writes an integer and string onto the end of a queue. The integer and string have no meaning to
the queue system, they are just passed from QueWrite() to QueRead(). Queue data is written to
the end of the queue. When the data is later read from the queue, it is returned on a first-in-first-
out basis.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax QueWrite(hQue, Type, Str)

hQue................The queue handle, returned from the QueOpen() function. The queue handle
identifies the table where all data on the associated queue is stored.
 QueWrite 493

Type .................The integer to put into the queue.

Str ....................The string to put into the queue.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions QueClose, QueLength, QueOpen, QueRead, QuePeek
Examples
QueWrite(hQue,2,"Hello there");
QueWrite(hQue,4,"Help");

RadToDeg
Description Converts an angle from radians to degrees.
Syntax RadToDeg(Angle)

Angle................Any angle (in radians).

Return Value The angle in degrees.

Related Functions DegToRad
Examples
Variable=RadToDeg(Pi());
! Sets Variable to 180.

Rand
Description Generates a random number between 0 and a specified maximum number.
Syntax Rand(Maximum)

Maximum .........The maximum number. This number must be between 2 and 32767
(inclusive).

Return Value A random number of integer type.

Examples
Variable=Rand(100);
! Sets Variable to a random number from 0 to 100.

// To create a random number between 0 and 1 with 2 decimal places,

divide the above variable by 100, as shown here: //
494 Rand

Variable = Variable/100;

RealToStr
Description Converts a floating-point number into a string.
Syntax RealToStr(Number, Width, Places)

Number............ The floating-point number to convert.

Width ...............The width of the string.

Places.............. The number of decimal places contained in the string.

Return Value The floating-point number (as a string).

Related Functions StrToReal
Examples
Variable=RealToStr(12.345,10,1);
! Sets Variable to " 12.3" (10 characters long).

RepGetControl
Description Gets report control information on a report. This function is a blocking function. It will block
the calling Cicode task until the operation is complete.
Syntax RepGetControl(Name, Type)

Name ............... The name of the report.

Type.................The type of report control information to get (send back in the return value):

0 .... State of the report - returns one of:

0 .... Idle
1 ..... Waiting for PLC data for trigger
2 ..... Waiting for PLC data
3 .... Running
1 .... Time of day that the report is due to run next.
2 .... The report period, in seconds, or week day, month or year, e.g. if the report
is weekly, this is the day of the week, 0 (Sunday) to 6 (Saturday).
 RepGetControl 495

3 .... Synchronisation time of day of the report, e.g. 10:00:00 (In seconds from
midnight).
4 .... Type of report schedule - returns one of:
0 .... Event triggered
1 .... Daily
2 .... Weekly
3 .... Monthly
4 .... Yearly
5 .... Report state - returns one of:
0 .... Enabled
1 .... Disabled

Return Value The control information, as an integer.

Related Functions RepSetControl, Report
Examples
Next=RepGetControl("SHIFT",1);
! Sets Next to the time that the report is due to run.

! Display a message at the prompt AN if the report is running.

IF RepGetControl("SHIFT",0)=3 THEN
Prompt("Shift report is running");
END

Report
Description Runs a report on the report server. This function only schedules the report for execution. The
running of the report is controlled entirely by the report server.
This function will start the specified report on the Reports Server to which the Citect computer is
communicating. If you are using the Reports Servers in Primary/Standby mode, the report can
run on the Standby Server. If you call this function on the Standby Server then the report will
definitely run on the Standby Server, even if the Primary Server is active.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax Report(Name)

Name................The name of the report to run.

496 Report

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions RepSetControl, RepGetControl
Examples

Buttons
Text Shift Report

Command Report("Shift")

Comment Runs the Shift Report

System Keyboard
Key Sequence Report ############ Enter

Command Report(Arg1)

Comment Runs a specified Report

Report("SHIFT");
! Runs the report named "SHIFT".
Report("DAY");
! Runs the report named "DAY".

/* The "SHIFT" and "DAY" reports are started. The order in which the
reports are run cannot be determined. If you want the "DAY" report to
run after the "SHIFT" report, call Report("DAY") at the end of the
"SHIFT" report. */

RepSetControl
Description Sets report control information to temporarily override the normal settings for a specified report.
You can change the report schedule for a periodic report, and run one-off or event-triggered
reports. These new settings are set on both the primary and standby report servers, but are not
saved to the database. When you restart your system, Citect uses the existing settings, defined in
the Reports database.
You might need to call this function several times. For example, to change an event-triggered
report to run at 6 hourly intervals, you need to change the schedule (Type 4), synchronisation
time (Type 3), and period (Type 2). If you use incompatible values for these options, you can
 RepSetControl 497

get unpredictable results. To change more than one option, disable the report, set the options,
and then re-enable the report.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax RepSetControl(Name, Type, Data)

Name................The name of the report.

Type .................The type of report control information to set:

1 ..... The time of day at which to run the next report. Subsequent reports are run
at the times calculated from the period (Type 2) and synchronisation time
(Type 3).
....... Use Type 1 to specify a one-off report. Set the time in Data in seconds
from midnight (e.g. specify 6 p.m. as 18 * 60 * 60).
2 ..... The report period. Set the new period in Data according to the report
schedule (Type 4), in seconds from midnight, day of week (0 to 6,
Sunday = 0), month (1 to 12), or year.
....... For a daily report schedule, set the report frequency in Data in seconds
from midnight; e.g. set Data to 6 * 60 * 60 for a 6 hourly shift report. If
the report is weekly, set Data to the day of the week, e.g. when Data = 2,
the day is Tuesday.
3 ..... Synchronisation time of day of the report. Set the time in Data in seconds
from midnight, e.g. to synchronise at 10a.m., set Data to 10 * 60 * 60.
4 ..... Type of report schedule. Set Data to one of the following:
0 ..... Event triggered
1 ..... Daily
2 ..... Weekly
3 ..... Monthly
4 ..... Yearly
5 ..... Report state. Set Data to either:
0 ..... Enabled
1 ..... Disabled

Data.................The new data value, dependent on the Type.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions RepGetControl, Report
498 RepSetControl

Examples
RepSetControl("Shift",1,TimeCurrent()+60);
! Runs the "Shift" report in 1 minute.

! change weekly report to 8 hour shift starting at 7 am

RepSetControl("Weekly", 5, 1); ! disable report
RepSetControl("Weekly", 4, 1); ! change mode to daily
RepSetControl("Weekly", 3, 7 * 60 * 60); ! sync at 7:00:00 am
RepSetControl("Weekly", 2, 8 * 60 * 60); ! run every 8 hours
RepSetControl("Weekly", 5, 0); ! enable report

! change yearly report to run on March 10 at 7 am

RepSetControl("Yearly", 5, 1); ! disable report
RepSetControl("Yearly", 4, 4); ! change mode to yearly
RepSetControl("Yearly", 3, 7 * 60 * 60); ! sync at 7:00:00 am
RepSetControl("Yearly", 2, 31 + 28 + 10); ! run on March 10th
RepSetControl("Yearly", 5, 0); ! enable report

ReRead
Description Re-reads all the I/O Device data associated with the current Cicode task. Citect normally keeps
the I/O Device data current. However, if a section of Cicode takes a very long time to run,
Citect's copy of the I/O Device data can become old and require re-reading.
This function requests all I/O Device data for the task so it could take a long time to complete
(e.g. up to 5 seconds), and the Cicode task will run slowly. You might have to use this function
if you have a task that runs in a loop forever, or that uses the Sleep() function, but only use this
function if you must.
ReRead() can be called automatically or manually. This behaviour is controlled by the
CodeSetMode()function, and the [Code]AutoReRead parameter.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax ReRead(Mode)

Mode ...............The mode of the read:

0 .... Read only if data is stale.

1 .... Read anyway.

Return Value No value (void).

Related Functions Sleep, TaskNew
Examples
 ReRead 499

WHILE 1 DO
.
.
! Sleep for 1 hour.
Sleep(3600);
ReRead(0);
END

Round
Description Rounds a number to a specified number of decimal places.
Syntax Round(Number, Places)

Number ............The floating-point number to round.

Places ..............The number of decimal places.

Return Value The number rounded to Places decimal places.

Examples
Variable=Round(0.7843,2);
! Sets Variable to 0.78 (result is rounded to 2 decimal places).

Variable=Round(123.45,-1);
! Sets Variable to 120.0 (rounded to -1 decimal place).

SemClose
Description Closes a semaphore opened with SemOpen(). You should close all semaphores when they are
no longer required, because they consume memory. If any Cicode tasks are waiting on this
semaphore, the tasks are released with an error.
Syntax SemClose(hSem)

hSem ................The semaphore handle, returned from the SemOpen() function. The semaphore
handle identifies the table where all data on the associated semaphore is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions SemOpen, SemSignal, SemWait
Examples
SemClose(hSem);
500 SemOpen

SemOpen
Description Opens a semaphore for access control. When the semaphore is opened, it is initially signalled.
Use a semaphore for controlling access to a restricted device, e.g. to stop another Cicode task
accessing a device while it is in use. You might require semaphores for some Cicode operations,
because they can access a device that is critical. (Cicode is a multi-tasking system.)
Syntax SemOpen(Name, Mode)

Name ............... The name of the semaphore.

Mode ...............The mode of the open:

0 .... Open existing semaphore.

1 .... Create new semaphore.
2 ..... Attempts to open an existing semaphore. If the semaphore does not exist, it
will create it.

Return Value The semaphore handle, or -1 if the semaphore was not opened successfully. The semaphore
handle identifies the table where all data on the associated semaphore is stored.
Related Functions SemClose, SemSignal, SemWait
Examples
hSem=SemOpen("MySem",1);

SemSignal
Description Signals a semaphore. If several Cicode tasks are waiting on this semaphore, the first task is
released. This function is a blocking function. It will block the calling Cicode task until the
operation is complete.
Syntax SemSignal(hSem)

hSem................The semaphore handle, returned from the SemOpen() function. The semaphore
handle identifies the table where all data on the associated semaphore is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions SemClose, SemOpen, SemWait
Examples
SemSignal(hSem);
 SemWait 501

SemWait
Description Waits on a semaphore to be signalled. This function is a blocking function. It will block the
calling Cicode task until the operation is complete.
Syntax SemWait(hSem, Timeout)

hSem ................The semaphore handle, returned from the SemOpen() function. The semaphore
handle identifies the table where all data on the associated semaphore is stored.

Timeout............Semaphore time-out time:

-1 .... Wait until semaphore is clear (regardless of how long).

0 ..... Do not wait - return immediately. (This timeout can be used to check the
state.)
>0 ... The number of seconds to wait if semaphore is not signalling, then return.

Return Value 0 (zero) if the semaphore has been gained, otherwise an error is returned.
Related Functions SemClose, SemOpen, SemSignal
Examples
Status=SemWait(hSem,10);
IF Status=0 THEN
.
.
ELSE
Prompt("Could not get semaphore");
END

SendKeys
Description Sends a keystroke (or string of keystrokes) to a window as if they were typed on the keyboard.
The window receives input focus and is brought to the foreground.
Syntax SendKeys(sTitle, sKeys)

sTitle ................The title (caption) of the destination window.

sKeys................The key (or keys) to send to sTitle.

To send a single keyboard character, use the character itself. For example, to
send the letter a, set sKeys to a.
502 SendKeys

To send more than one character, append each additional character to the string.
For example, to send the letters a, b, and c, set sKeys to abc.
The plus (+), caret (^), and percent sign (%) have special meanings. To send one
of these special characters, enclose the character with braces. For example, to
send the plus sign, use {+}. To send a { character or a } character, use {{} and
{}}, respectively.
To specify characters that are not displayed when you press a key (such as Enter
or Tab) and other keys that represent actions rather than characters, use the codes
shown below:
Key .............Code
Backspace ..{backspace} or {bs} or{bksp}
Break..........{break}
Caps Lock ..{capslock}
Clear...........{clear}
Del .............{delete} or {del}
End.............{end}
Enter...........{enter} or ~
Esc .............{escape} or {esc}
Help ...........{help}
Home .........{home}
Insert ..........{insert}
Num Lock ..{numlock}
Page Down.{pgdn}
Page Up......{pgup}
Print Screen{prtsc}
Scroll Lock.{scrolllock}
Tab .............{tab}
Up Arrow...{up}
Down Arrow {down}
Right Arrow {right}
Left Arrow .{left}
F1 ... {f1}
 SendKeys 503

F2 ... {f2}
F3 ... {f3}
F4 ... {f4}
F5 ... {f5}
F6 ... {f6}
F7 ... {f7}
F8 ... {f8}
F9 ... {f9}
F10 ............ {f10}
F11 ............ {f11}
F12 ............ {f12}
To specify keys combined with any combination of Shift, Ctrl, and Alt, precede
the regular key code with one or more of these codes:

Key ............ Code

Shift........... +
Ctrl ............ ^
Alt ............. %
To specify that Shift, Ctrl, and/or Alt are held down while several keys are
pressed, enclose the keys in parentheses. For example, to hold down
the Shift key while sending E then C, use +(EC). To hold down
Shift while sending E, followed by C without the Shift key, use
+EC. To specify repeating keys, use the form {key number}. For
example, {left 42} means send the left arrow key 42 times. Note
that you must leave a space between the key and number.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WndFind
Examples
SendKeys("Notepad", "abc");
// Send the key sequence "abc" to the Notepad application
504 SerialKey

SerialKey
Description Redirects all serial characters from a port to the keyboard. If you are using a keyboard attached
to a serial port, you should call this function at startup, so that Citect copies all characters (read
from the port) to the keyboard. The Port must be defined in the Ports database.
If the port is not on an I/O server, you must create a dummy I/O server record (e.g. name the
server DServer1). Complete the Boards and Ports records. Set the following parameters in the
CITECT.INI file:
[IOServer]Name to the server name (e.g. DServer1)
[IOServer]Server to 0
This method enables the port without making the computer an I/O Server. (If the I/O Server is
enabled (and not required as an I/O server), extra overhead and memory are used.)
This function can only be called from an I/O Server.
Syntax SerialKey(sPort)

sPort................The name of the port connected to the serial keyboard.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ComOpen
Examples
SerialKey("Port1"); ! enable the serial keyboard

ServerInfo
Description Gets status information on clients and servers.
Syntax ServerInfo(Name, Type)

Name ............... The name of the client or server, either "Client", "Server", "Alarm", "Trend", or
"Report".

You can also pass a number instead of the name (but it still must be enclosed in
quotes). The number represents the target client. For example, if there are 12
clients, passing "3" will get information on the 3rd client.
NOTE: If this server is an Alarm, Trend, Report, and I/O Server then each client
will be attached 4 times. So 12 clients would mean there are 3 Citect computers
using this server - one of which is itself.

Type.................The type of information required (depends on the Name you specify):

"Alarm", "Trend", or "Report":

 ServerInfo 505

0 .... Primary flag (returns 1 if this is a primary server, 0 if a standby server).

1 ..... Number of clients attached to this server.
2 ..... If this client is attached to the primary or standby server for the specified
server name. If Name is "Alarm" and if this client is attached to the
primary alarm server, the return value is 0. If this client is attached to the
standby, the return value is 1.
3 ..... The status of the client connection to the specified server name. If Name is
"Report" and the client is talking to a report server (either primary or
standby), the return value is 1. If not, the return value is 0.
"Client":
0 .... The computer name, as specified by [LAN] Computer.
1 ..... The primary server name, as specified by [Client] Primary in the Citect.INI
file.
2 ..... The secondary server name, as specified by [Client] Standby in the
Citect.INI file. If no secondary server is specified, an empty string is
returned.
3 ..... The name of the INI file being used, e.g. Citect.INI.
"Server":
0 ..... The server name, as specified by [Server] Name.
1 ..... The number of clients attached to this server. This is the total number of
Alarm, Trend Report, and I/O Server clients.
"<number>":
0 ..... The name of the server this client is talking to. For example, "Alarm",
"Trend", "Report", or "IOServer".
1 ..... The login name of the client. This may be an empty string if the client has
not logged in.
2 ..... The Citect computer name of the client computer.
3 ..... The time the client logged in.
4 ..... The number of messages received from this client.
5 ..... The number of messages sent to this client.
6 ..... If this client has a licence (1) from this server or not (0).
7 ..... The type of the licence; full licence (0), manager client (1), or display client
(2).
8 ..... If the client is remote (1) or local (0).
506 ServerInfo

Return Value Status information specified by Type.

Examples
sSrvInfo=ServerInfo("Report",0);
IF sSrvInfo THEN
! This is a primary report server.
ELSE
! This is a stand-by report server.
END

/* Get and store the names of all clients attached to this server */
iCount = 1;
iClients = ServerInfo("Server", 1);

WHILE iCount <= iClients DO

sName[iCount] = ServerInfo(IntToStr(iCount), 2);
iCount = iCount + 1;
END

SetArea
Description Sets the current viewable areas. You can pass a single area number, or a group of areas to set
multiple areas. You can only set areas that are flagged for the current user (defined in the Users
database).
Syntax SetArea(Area)

Area.................The area to set (1 to 255).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen
Examples
/* Set current viewable area to Area 1. */
SetArea(1);

SetEvent
Description Sets an event callback function by specifying a function handle. You can use this function with
the GetEvent() function to restore an old event handler.
Syntax SetEvent(Type, hFn)

Type.................The type of event:

 SetEvent 507

0 .... The mouse has moved. When the mouse moves the callback function is
called. The return value must be 0.
1 .... A key has been pressed. When the user presses a key, the callback function
is called after Citect checks for hot keys. If the return value is 0, Citect
checks for key sequences. If the return value is not 0, Citect assumes that
you will process the key and does not check the key sequence. It is up to
you to remove the key from the key command line.

NOTE:....... If you are using a right mouse button click as an event, you should
read about the ButtonOnlyLeftClick parameter.
2 .... Error event. This event is called if an error occurs in Cicode, so you can
write a single error function to check for your errors. If the return value is
0, Citect continues to process the error and generates a hardware error - it
may then halt the Cicode task. If the return value is not 0, Citect assumes
that you will process the error, and continues the Cicode without generating
a hardware error.
3 ..... Page user communication error. A communication error has occurred in
the data required for this page. If the return value is 0 (zero), Citect still
animates the page. If the return value is not zero, Citect does not update the
page.
4 ..... Page user open. A new page is being opened. This event allows you to
define a single function that is called when all pages are opened. The return
value must be 0.
5 ..... Page user close. The current page is being closed. This event allows you to
define a single function that is called when all pages are closed. The return
value must be 0.
6 ..... Page user always. The page is active. This event allows you to define a
single function that is called when all pages are active. The return value
must be 0.
7 ..... Page communication error. A communication error has occurred in the
data required for this page. Reserved for use by Citect.
8 ..... Page open. This event is called each time a page is opened. Reserved for
use by Citect.
9 ..... Page close. This event is called each time a page is closed. Reserved for
use by Citect.
10.... Page always. This event is called while a page is active. Reserved for use
by Citect.
11..17 Undefined.
18.... Report start. The report server is about to start a new report. This event is
called on the report server. The return value must be 0.
508 SetEvent

19 ... Device history. A device history has just completed. The return value must
be 0.
20 ... Login. A user has just logged in.
21 ... Logout. A user has just logged out.
22 ... Trend needs repainting. This event is called each time Citect re-animates a
real-time trend or scrolls an historical trend. You should use this event to
add additional animation to a trend, because Citect deletes all existing
animation when a trend is re-drawn. (For example, if you want to display
extra markers, you must use this event.)
23 ... Hardware error occurred.
24 ... Keyboard cursor moved. This event is called each time the keyboard
command cursor moves. The cursor can be moved by the cursor keys, the
mouse, or the Cicode function KeySetCursor(). Note that you can find
where the keyboard command cursor is located by calling the function
KeyGetCursor().
25 ... Network shutdown. A Shutdown network command has been issued.
26 ... Runtime system shutdown and restart. (Required because of configuration
changes.)
27 ... Event. An event has occurred.
28 ... Accumulator. An accumulator has logged a value.
29 ... Slider. A slider has been selected.
30 ... Slider. A slider has moved.
31 ... Slider. A slider has been released (i.e. stopped moving).

NOTE: .......1) While responding to slider events 29, 30, and 31, you can set any
variables but you cannot call functions that cause immediate changes
to animations on the page (e.g. DspText() and DspSym()).
2) Types 29, 30, & 31 relate only to V3.xx and V4.xx animations,
and will be superseded in future releases.
32 ... Shutdown. Citect is being shutdown.
33... 127 Reserved for future Citect use.
128... 256 ...User defined events. These events are for your own use.

hFn ..................The function handle, as returned from the GetEvent() function.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GetEvent
 SetEvent 509

Examples See GetEvent.

SetLanguage
Description Sets the language database from which the local translations of all native strings in the project
will be drawn, and specifies the character set to be used. Native strings are those that are
preceded by a @, and enclosed in brackets (e.g. @(Motor Overload)).
This function will dynamically change the language of display items such as alarm descriptions,
button text, keyboard/alarm logs, graphic text, Cicode strings etc. The language will only be
changed on the display client that calls the function. This means that you can display different
languages at different display clients, even though they are running the same project.
If the local language character set differs from the default character set of the Windows
installation, the runtime text may be garbled. You can set the local language and character set by
using this function, or through the [Language]LocalLanguage and [Language]CharSet
Parameters.
Syntax SetLanguage(sLanguage, nCharSet)

sLanguage .......The name of the language database from which the local translations of all native
strings in the project will be drawn. You do not need the .dbf extension.

nCharSet..........The character set to use when displaying the localised text in runtime:

0 ..... ANSI
1 ..... Default
128............. Japanese - Shiftjis
129............. Korean - Hangul
130............. Korean - Johab
134............. Chinese - simplified
136............. Chinese - traditional
161............. Greek
162............. Turkish
163............. Vietnamese
177............. Hebrew
178............. Arabic
186............. Baltic
204............. Russian
510 SetLanguage

222 .............Thai
238 .............East European

Return Value 0 (zero) if successful, otherwise 262 (the file could not be opened).
Related Functions LanguageFileTranslate, StrToLocalText.
Examples
SetLanguage("French",1);
! Changes the current language to French, using the Windows default
character set.

Shutdown
Description Terminates Citect's operation. You should always use this function to shut down the Citect
system, otherwise buffered data could be lost.
The shutdown can affect only the computer that calls it, or all or part of a Citect network. If you
are shutting down a network, specify the computers (Display Clients and servers) to be shut
down in sDest, and the extent of the shutdown in Mode.
You can allow selected computers to override the shutdown with the [Shutdown]NetworkIgnore
parameter. (You might set this parameter for critical servers, e.g. I/O Servers.)
Use the ShutdownForm() function to prompt the user for verification before shutting Citect
down.
Syntax Shutdown(sDest, sProject, Mode)

sDest................ The destination computer(s) to be shut down, as a string:

"" ...............(blank string) This computer only

["Computer_Name"] The specified Citect Display Client (defined in the
computer's CITECT.INI file)
["Server_Name"] The specified Citect server
"All Clients" All Citect Display Clients on the network
"All Servers" All Citect servers on the network
"Everybody" All Citect computers on the network

sProject ...........The name of the project (for example "DEMO"), or the path to the project. If
you specify the path to the project, you must use the full path, for example to
specify the path to the project "Demo", use: "C:\CITECT\USER\DEMO". If you
do not specify a project, the current project will be used.
 Shutdown 511

Mode................The type of shutdown:

1 ..... Shutdown Citect

2 ..... Shutdown and restart Citect
3 ..... Shutdown and restart Citect and Windows
4 ..... Shutdown Citect and re-boot the computer
6 ..... Shutdown, but do not shutdown this computer

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions ProjectRestartGet, ProjectRestartSet, ProjectSet, ShutdownMode, ShutdownForm, OnEvent
Examples
/* Shut down Citect on this computer. */
Shutdown();

/* Shut down and restart Citect clients, but not this computer. */
Shutdown("All Clients", ProjectRestartGet(), 6);

ShutdownForm
Description Displays a dialog box to verify that the user really wants to shut down the Citect system. If the
user selects [Yes], Citect will be shut down.
This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
Syntax ShutdownForm()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Shutdown
Examples

System Keyboard
Key Sequence Shutdown

Command ShutdownForm();

Comment Display the shutdown form

512 ShutdownForm

Buttons
Text Shutdown

Command ShutdownForm();

Comment Display the shutdown form

ShutdownMode
Description Gets the mode of the shutdown. The mode is used for an online restart, to specify whether
changes made to the project were global or to pages only. If the mode is pages only, only the
graphics pages are shut down and reopened (with changes). If the mode is global, Citect is shut
down and restarted.
Syntax ShutdownMode()

Return Value The shutdown mode set when shutdown was called.
Related Functions Shutdown
Examples
nMode = ShutdownMode()
If nMode = 4 Then
Prompt ("Rebooting your Computer")
END

Sign
Description Gets the sign of a number.
Syntax Sign(Number)

Number............ Any number.

Return Value The sign of Number.

Related Functions Abs
Examples
Variable=Sign(100);
! Sets Variable to 1.
Variable=Sign(-300);
 Sign 513

! Sets Variable to -1.

Variable=Sign(0);
! Sets Variable to 0.

Sin
Description Calculates the trigonometric sine of an angle.
Syntax Sin(Angle)

Angle................Any angle (in radians).

Return Value The sine of Angle.

Related Functions ArcSin
Examples
Variable=Sin(0.7854);
! Sets Variable to 0.7071...

Sleep
Description Suspends the current Cicode task for a specified number of seconds. After the time delay, the
Cicode task wakes and continues execution. If the sleep time is 0, the Cicode task is pre-empted
for 1 time slice only.
This function does not affect any other Cicode tasks - only the task calling Sleep() is suspended.
If you have Cicode that runs continuously in a loop, you should call the Sleep() function
somewhere within the loop, to pause the loop and allow other tasks to run.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax Sleep(Seconds)

Seconds............The number of seconds. Set to 0 to pre-empt the task for one time-slice.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TaskNew, ReRead SleepMS
514 Sleep

Examples

Buttons
Text Step

Command PLCBit=1;Sleep(2);PLCBit=0;

Comment Switch Bit ON and then OFF 2 seconds

later

! Display "Hello" 10 times at 60 second intervals.

WHILE I<10 DO
Sleep(60);
Prompt("Hello");
I=I+1;
END

! Sleep a while in polling loops

WHILE < waiting for event or time> DO
! do what ever here
.
.
Sleep(10); ! sleep a while to give other tasks a go.
! the longer the sleep the better for other tasks.
END

SleepMS
Description Suspends the current Cicode task for a specified number of milliseconds. After the time delay,
the Cicode task wakes and continues execution. This function is similar to the Sleep function but
with greater resolution.
Although a value of 0 Milliseconds is accepted, it is not recommended. Try to use at least a
value of 1.
This function does not affect any other Cicode tasks - only the task calling SleepMS() is
suspended. If you have Cicode that runs continuously in a loop, you should call the SleepMS()
or Sleep() function somewhere within the loop, to pause the loop and allow other tasks to run.
This function is a blocking function. It will block the calling Cicode task until the operation is complete.
Syntax SleepMS(Milliseconds)

Milliseconds ....The number of milliseconds (1000 milliseconds per second). Set to 0 to pre-
empt the task for one time-slice. Be careful not to use a value that is too small.
Setting the value to 0 would generally have no desirable effect.
 SleepMS 515

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TaskNew, ReRead, Sleep
Examples

Buttons
Text Step

Command PLCBit=1;SleepMS(500);PLCBit=0;

Comment Switch Bit ON and then OFF 500 milliseconds later.

! Increment a memory variable by ten, 120 times over one minute (twice a second).
I=0;
WHILE I<180 DO
SleepMS(500);
iRamp = iRamp + 10;
I=I+1;
END

! sleep a while in polling loops

WHILE < waiting for event or time> DO
! do what ever here
.
.
SleepMS(200); ! sleep a while to give other tasks a go.
! the longer the sleep the better for other tasks.
END

SPCAlarms
Description Returns the status of the specified SPC alarm. This function is used to configure SPC alarms, by
defining alarms with this trigger in Advanced Alarms.
Syntax SPCAlarms(sSPCTag, AlarmType)

sSPCTag ..........The SPC Tag name as defined in SPC Tags.

AlarmType .......The description of the alarm type. The following types are valid:

XFreak
XOutsideCL
XAboveUCL
516 SPCAlarms

XBelowLCL
XOutsideWL
XGradualUp
XGradualDown
XUpTrend
XDownTrend
XErratic
XStratification
XMixture
ROutsideCL
RAboveUCL
RBelowLCL
For more information about these alarms read the SPC Alarms section.

Return Value Alarm status, ON (1) or OFF (0).

Related Functions AlarmAck
Examples

Advanced Alarms
Alarm Tag Feed_SPC_XBLCL

Alarm Desc Process mean below LCL

Expression SPCAlarms("Feed_SPC", XBelowLCL)

Comment Trigger an alarm when XBelowLCL condition

becomes true.
 SPCAlarms 517

Advanced Alarms
Alarm Tag Temp_SPC_GRADUP

Alarm Desc Mean is drifting up

Expression SPCAlarms("Temp_SPC", XGradualUp)

Comment Trigger an alarm if mean drifts up.

SPCClientInfo
Description Returns SPC data for the given SPC tag. The information retrieved through this function is from
the cache maintained by the display client. This function will give a faster response than the
related functions which access the SPC (trend) server.
This function can only be called while on an SPC page.
Syntax SPCClientInfo(sSPCTag, iType)

sSPCTag ..........The SPC Tag name as defined in SPC Tags.

iType ................The information to be returned:

1 .... Subgroup Size

2 ..... No. of Subgroups
3 ..... Process Mean (x double bar)
4 ..... Process Range
5 ..... Process Standard Deviation
6 ..... Lower Specification Limit (LSL)
7 ..... Upper Specification Limit (USL)
8 ..... Cp - Process Capability Actual
9 ..... Cpk - Process Capability Potential
10.... Process Skewness
11.... Process Kurtosis

Return Value The requested data specified by iType. It is of type REAL.

Related Functions SPCSpecLimitGet, SPCProcessXRSGet, SPCSubgroupSizeGet.
518 SPCClientInfo

Examples
/* This function will check the capability of a particular SPC
tag.*/
REAL
FUNCTION
CheckCapability(STRING sTAG)
REAL rReturn;

rReturn = SPCClientInfo(sTag, 8);

!rReturn holds the inherent capability value

IF rReturn > 1.0 THEN

Message(sTag + "Assessment","The process is Capable.",64);
ELSE
Message(sTag + "Assessment","The process is not Capable.",64);
END
Return rReturn;
END

SPCGetHistogramTable
Description Returns an array containing the frequencies of particular ranges for the given SPC tag. The
histogram structure is implied in the order of the table as follows - the first array element is the
data less than -3 sigma. The second value is the data between -3 sigma and -3 sigma plus the bar
width etc. The last value is the data greater than +3 sigma.
This function can only be called while on an SPC page.
Syntax SPCGetHistogramTable(sSPCTag, iNoBars, TableVariable)

sSPCTag..........The SPC Tag name as defined in SPC Tags.

iNoBars ........... The number of bars in the table. The valid range is restricted to values from 7 to
100. This also indicates the size of the array to be returned.

TableVariable..The Cicode array that will store the histogram data. This variable must be
defined as a global array of type INT. The number of elements in the array must
be equal to (or greater than) iNoBars.

Return Value 0 (zero) if successful, otherwise an error number is returned. The histogram table is written to
TableVariable.
Related Functions TableMath.
 SPCGetHistogramTable 519

Examples
/* This function will get the maximum frequency present in the
histogram of a particular SPC tag.*/
INT iFrequency[7];
! This variable must be global to the file so is declared outside of the
function

INT
FUNCTION
GetMaxFreq(STRING sTAG)
INT iError;
INT iMax = -1;

iError = SPCGetHistogramTable(sTag, 7, iFrequency);

!The elements of iFrequency now hold the histogram table frequencies.

IF iError = 0 THEN
! Get maximum
iMax = TableMath(iFrequency,7,1,0);
END
Return iMax;
END

SPCGetSubgroupTable
Description Returns an array containing the specified subgroup's elements with the mean, range and standard
deviation. The data will be in the following order:
Element0, Element1, ... , Element(n-1), Mean, Range, StdDev.
Where n is the subgroup size.
This function can only be called while on an SPC page.
Syntax SPCGetSubgroupTable(sSPCTag, iSubgroup, TableVariable)

sSPCTag ..........The SPC Tag name as defined in SPC Tags.

iSubgroup ........The number of the subgroup being displayed whose data is to be retrieved. Zero
('0') represents the most recent subgroup.

TableVariable..The first element of the Cicode array that will store the sample data. This
variable must be defined as a global array of type REAL. The number of
elements in the array must be equal to (or greater than) the subgroup size + 3.

Return Value 0 (zero) if successful, otherwise an error number is returned. The subgroup's data is written to
TableVariable.
520 SPCGetSubgroupTable

Related Functions TableMath.

Examples
/* This function will get the minimum value present in the sample
data of a particular SPC tag.*/
REAL rSubgroup[8]; ! 5 samples + mean + range + stddev.
! This variable must be global to the file, so is declared outside of
the function

REAL
FUNCTION
GetMinSample(STRING sTAG)
INT iError;
REAL iMin = 0;

iError = SPCGetSubgroupTable(sTag, 7, rSubgroup);

!The elements of rSubgroup now hold the group samples, mean, range and
stddev.

IF iError = 0 THEN
! Get minimum. Note that the range of data is 5
iMin = TableMath(rSubgroup,5,0,0);
END
Return iMin;
END

SPCPlot
Description This function is designed to work only on an SPCXRSChart page. It prints a single page
showing three separate trends of the SPC Mean, Range, and Standard Deviation. The Mean
must be at hAn, the Range at hAn + 1, and the Standard Deviation at hAn + 2. You can specify a
title and a comment for the plot, and whether it is printed in colour or in black and white.
Syntax SPCPlot(sPort, hAn, sTitle, sComment, iMode)

sPort................The name of the printer port to which the plot will be printed. This name must
be enclosed within quotation marks. For example LPT1:, to print to the local
printer, or \\Pserver\canon1 using UNC to print to a network printer.

hAn ..................The animation point at which the Mean chart is currently situated. The Range
and Standard Deviation charts must be on the next two consecutive animation
numbers. For example, if the Mean chart is at animation point 40, the Range
chart must be at animation point 41, and the Standard Deviation chart must be at
animation point 42.

sTitle................ The title of the trend plot.

 SPCPlot 521

sComment ........The comment that is to display beneath the title of the trend plot. You do not
have to enter a comment.

iMode...............The colour mode of the printer.

0 ..... Black and White (default)

1 ..... Colour

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnPlot, TrnComparePlot. TrnPrint. PlotOpen
Examples
/* This function will print the Mean trend (currently displayed at
animation point 40), the Range trend (currently at animation point 41),
and the Standard Deviation trend (currently at animation point 42). The
result is a one page, black and white combination of all three trends,
printed to LPT1. */

SPCPlot("LPT1:",40, "Citect SPC Chart","Gradually increasing trend",0);

SPCProcessXRSGet
Description Gets the process mean, range, and standard deviation overrides for the specified SPC tag. The
values that are returned are the values that are currently being used by the SPC (trend) server, not
necessarily the values specified in the SPC Tag definition.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
This function can only be called while on an SPC page.
Syntax SPCProcessXRSGet(sSPCTag, XVariable, RVariable, SVariable)

sSPCTag ..........The SPC Tag name as defined in SPC Tags.

XVariable ........The Cicode variable that stores the process mean (X double bar). This variable
must be defined as a global of type REAL. Do not specify a constant in this
field.

RVariable ........The Cicode variable that stores the range (R). This variable must be defined as a
global of type REAL. Do not specify a constant in this field.

SVariable.........The Cicode variable that stores the standard deviation (S). This variable must be
defined as a global of type REAL. Do not specify a constant in this field.
522 SPCProcessXRSGet

Return Value 0 (zero) if successful, otherwise an error number is returned. The process mean is written to
XVariable, the process range to RVariable, and the standard deviation to SVariable.
Related Functions SPCClientInfo, SPCProcessXRSSet.
Examples
/* This function will set a new override value for Mean, without
overwriting the values already in place for Standard Deviation and Range
*/
REAL rOldMean;
REAL rRange;
REAL rStdDev;
! These variables must be global to the file, so are declared outside of
the function

INT
FUNCTION
Tank1SPCNewMean(REAL rNewMean)
INT iError;

iError = SPCProcessXRSGet("TANK_1_TEMP", rOldMean, rRange, rStdDev);

! If no error, rOldMean, rRange and rStdDev now hold the current values
of XRS.

IF iError = 0 THEN
iError = SPCProcessXRSSet("TANK_1_TEMP", rNewMean, rRange, rStdDev);
END
Return iError;
END

SPCProcessXRSSet
Description Sets the process mean, range and standard deviation overrides for the specified SPC tag. The
values entered here will override Citect's automatic calculations, and the overrides specified in
the SPC Tags definition.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
This function can only be called while on an SPC page.
Syntax SPCProcessXRSSet(sSPCTag, rMean, rRange, rStdDev)

sSPCTag..........The SPC Tag name as defined in SPC Tags.

rMean .............. The new value of process mean (x double bar) to set.
 SPCProcessXRSSet 523

rRange .............The new value of process range to set.

rStdDev............The new value of process standard deviation to set.

Return Value 0 (zero) if successful, otherwise an error number is returned.

Related Functions SPCProcessXRSGet.
Examples See the example for SPCProcessXRSGet.

SPCSetLimit
Description Sets the upper or lower control limits of X-bar, range, or standard deviation charts. Using this
function will only set the controller limits on the Client display which will not affect the SPC
Alarms. To set the server control limits, use the SPCProcessXRSSet function.
Syntax SPCSetLimit(AN, Type, Value, Setting)

AN....................The AN where the SPC chart is located.

Type .................The SPC type:

1 ..... X-bar upper control limit

2 ..... X-bar lower control limit
3 ..... Range upper control limit
4 ..... Range lower control limit
5 ..... Standard deviation upper control limit
6 ..... Standard deviation lower control limit
7 ..... X-bar centre line
8 ..... Range centre line
9 ..... Standard deviation centre line

Value................The value for the control limit.

Setting..............Automatic calculation or manual setting of control limits:

0 ..... Automatic
1 ..... Manual

Return Value 0 (zero) if successful, otherwise an error is returned.

524 SPCSetLimit

Examples
SPCSetLimit(40,1,250,1);
! Sets X-bar upper control limit to 250 at AN40.

SPCSpecLimitGet
Description Gets the process Upper and Lower Specification Limits (USL and LSL) for the specified SPC
tag. The values that are returned are the values that are currently being used by the SPC (trend)
server, not necessarily the values specified in the SPC Tag definition.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
This function can only be called while on an SPC page.
Syntax SPCSpecLimitGet(sSPCTag, LSLVariable, USLVariable)

sSPCTag..........The SPC Tag name as defined in SPC Tags.

LSLVariable ....The Cicode variable that stores the Lower Specification Limit (LSL). This
variable must be defined as a global of type REAL. Do not specify a constant in
this field.

USLVariable....The Cicode variable that stores the Upper Specification Limit (USL). This
variable must be defined as a global of type REAL. Do not specify a constant in
this field.

Return Value 0 (zero) if successful, otherwise an error number is returned. The LSL is written to
LSLVariable, while the USL is written to USLVariable.
Related Functions SPCClientInfo, SPCSpecLimitSet.
Examples
/* This function will increase the current USL and LSL of the
specified Tag by 10 percent.*/
REAL rLSL;
REAL rUSL;
! These variables must be global to the file, so are declared outside of
the function

INT
FUNCTION
ExpSLbyPercent(STRING sTAG)
REAL rIncPercent = 1.1;
REAL rDecPercent = 0.9;
INT iError;
 SPCSpecLimitGet 525

iError = SPCSpecLimitGet(sTag, rLSL, rUSL);

! If no error, rLSL and rUSL now hold the current values of LSL and USL
for sTAG

rLSL = rLSL * rDecPercent;

rUSL = rUSL * rIntPercent;

IF iError = 0 THEN
iError = SPCSpecLimitSet(sTAG, rLSL, rUSL);
END
Return iError;
END

! The function would be called as follows;

Page Button
Button Text Expand Temperature Limits
Expression ExpSLby10Percent("TANK_1_TEMP");

SPCSpecLimitSet
Description Sets the process Upper and Lower Specification Limits (USL and LSL) for the specified SPC
tag. The values entered here will override those specified in the SPC Tags definition.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
This function can only be called while on an SPC page.
Syntax SPCSpecLimitSet(sSPCTag, rLSL, rUSL)

sSPCTag ..........The SPC Tag name as defined in SPC Tags.

rLSL.................The new value of Lower Specification Limit (LSL) to set.

rUSL ................The new value of Upper Specification Limit (USL) to set.

Return Value 0 (zero) if successful, otherwise an error number is returned.

Related Functions SPCSpecLimitGet.
Examples See the example for SPCSpecLimitGet.
526 SPCSubgroupSizeGet

SPCSubgroupSizeGet
Description Gets the subgroup size for the specified SPC tag. The value that is returned is the value that is
currently being used by the SPC (trend) server, not necessarily the value specified in the SPC
Tag definition.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
This function can only be called while on an SPC page.
Syntax SPCSubgroupSizeGet(sSPCTag, SizeVariable)

sSPCTag..........The SPC Tag name as defined in SPC Tags.

SizeVariable ....The Cicode variable that stores the subgroup size. This variable must be defined
as a global of type INT. Do not specify a constant in this field.

Return Value 0 (zero) if successful, otherwise an error number is returned. The subgroup size is written to
SizeVariable.
Related Functions SPCClientInfo, SPCSubgroupSizeSet.
Examples See the example for SPCSubgroupSizeSet.

SPCSubgroupSizeSet
Description Sets a new subgroup size for the specified SPC tag. The new subgroup size becomes the new
size as long as the SPC (trend) server is running. The subgroup size is updated first in the SPC
server, which then informs all display clients to update. This will force re-calculation of SPC
values (UCL and LCL) across the span of any displayed charts.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
This function can only be called while on an SPC page.
Syntax SPCSubgroupSizeSet(sSPCTag, iSize)

sSPCTag..........The SPC Tag name as defined in SPC Tags.

iSize The new size of the subgroup to set.

Return Value 0 (zero) if successful, otherwise an error number is returned.
Related Functions SPCSubgroupSizeGet.
 SPCSubgroupSizeSet 527

Examples
/* This function increments the subgroup size for FEED_RATE_1 by
the specified amount. */
INT iSize;
! This variable must be global to the file, so is declared outside of
the function

INT
FUNCTION
IncSubgroupSize(INT iIncrement)
INT iError;

iError = SPCSubgroupSizeGet("FEED_RATE_1", iSize);

! If no error, iSize now contains the current subgroup size of
FEED_RATE_1

iSize = iSize + iIncrement;

IF iError = 0 and (isize > 1) THEN

iError = SPCSubgroupSizeSet("FEED_RATE_1", iSize );
END
Return iError;
END

SQLAppend
Description Appends a statement string to the SQL buffer. Cicode cannot send an SQL statement that is
longer than 255 characters. If you have an SQL statement that is longer than the 255 character
limit, you can split the statement into smaller strings, and use this function to append the
statements in the SQL buffer.
Syntax SQLAppend(hSQL, String)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

String ...............The statement string to append to the SQL buffer.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLSet, SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg
Examples See SQLSet.
528 SQLBeginTran

SQLBeginTran
Description Starts a database transaction. When you make a transaction, your changes are not written to the
database until you call the SQLCommit() function. Alternatively, you can use the SQLRollBack
function() to discard all changes made during the transaction.
After you begin a transaction, you must call either SQLCommit() to save the changes or
SQLRollBack() to discard the changesthese functions complete the transaction and release all
database locks. Unless you complete the transaction, you cannot successfully disconnect the
SQL connection.
A single database connection can only handle one transaction at a time. After you call
SQLBeginTran(), you must complete that transaction before you can call SQLBeginTran() again.
If you disconnect from a database while a transaction is active (not completed), Citect
automatically "rolls back" the transactionany changes you made to the database in that
transaction are discarded.
You do not need to begin a transaction to modify a database. Any changes you make to a
database before you call the SQLBeginTran() are automatically committed, and no database
locks are held.
The SQLBeginTran() function is not supported by all databases. If you have difficulty using the
function, check that both your database and ODBC driver support transactions. Refer to the
documentation for your database for more information on transactions.
Syntax SQLBeginTran(hSQL)

hSQL ............... The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec, SQLFieldInfo,
SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples
/* Increase each employee's salary and superannuation by a specified
amount. If any errors occur, the changes are aborted */
INT
FUNCTION
PayIncrease(STRING sIncrease)

INT hSQL;
INT Count1;
INT Count2;
hSQL = SQLConnect("DRV=QEDBF");
 SQLBeginTran 529

SQLBeginTran(hSQL);
SQLExec(hSQL, "UPDATE C:\DATA\EMPLOYEE SET Salary = Salary + "
+sIncrease);
Count1 = SQLNumChange(hSQL);
SQLExec(hSQL, "UPDATE C:\DATA\EMPLOYEE SET Super = Super + "
+sIncrease);
Count2 = SQLNumChange(hSQL);
IF Count1 = Count2 THEN
SQLCommit(hSQL);
ELSE
SQLRollBack(hSQL);
END
SQLEnd(hSQL);
SQLDisconnect(hSQL);
END

SQLCommit
Description Commits (to the database) all changes made within a transaction. If you call the
SQLBeginTrans() function to begin a transaction, you must call the SQLCommit() function to
save the changes you make to the database during that transaction (with the Insert, Delete, and
Update SQL commands).
The SQLCommit() and SQLRollBack() functions both complete a transaction and release all
database locks. But while the SQLCommit() function saves all changes made during the
transaction, the SQLRollBack() function discards these changes. Unless you call the
SQLCommit() function before you disconnect the database, Citect automatically rolls back the
transactionany changes you made to the database in that transaction are discarded.
The SQLCommit() function could affect different databases in different ways. If you have
difficulty using the function, check that your database is ODBC compatible. Refer to the
documentation for your database for more information on committing transactions.
Syntax SQLCommit(hSQL)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec, SQLFieldInfo,
SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples See SQLBeginTran.
530 SQLConnect

SQLConnect
Description Makes a connection to a database system, and returns a handle to the connection for use by the
other SQL functions. Through this connection, you can execute SQL statements in the specified
database. You must call this function before any other SQL function.
You only require one connection for each database system to be accessed (e.g. Oracle, dBASE,
Excel, etc.).
You should not use an SQL database for storage of real-time data (such as alarms), because SQL
databases do not provide real-time performance when accessing database data. Only use an SQL
database where data transfer is not critical (for example, recipes or reports). If you try to use
SQL to store real time data, Citect's performance could be greatly degraded.
Syntax SQLConnect(sConnect)

sConnect.......... The connection string, in the format:

<attribute>=<value>[;<attribute>=<value>. . .]
The following attributes can be used in a connection string:

DSN Data Source Name. The name of the data source defined with the ODBC utility in
the Windows Control Panel. You must use the DSN attribute, unless you are using
Citect v2.01 or earlier.

DLG Dialog box. Set DLG to 1 to display a dialog box that allows the user to input their
user ID, password, and connection string. DLG is an optional attribute.

UID User name or Authorisation/Login ID. Check the documentation for your ODBC
driver and database to see if you need to use the UID attribute.

PWD Password. Check the documentation for your ODBC driver and database to see if
you need to use the PWD attribute.

MODIFY The ability of Citect to understand and accept native SQL depends on the database
SQL driver being used. Set MODIFYSQL to 1 (the default) for an ODBC-compliant
SQL. Set MODIFYSQL to 0 to use the native SQL syntax of the database system,
as well as for any Citect databases you created with versions 2.01 or earlier, that
employ database-specific SQL statements. The Q+E ODBC database drivers are
backward compatible with those supplied with earlier versions of Citect.

REREAD Set to 1 to reread records from the database after updating them. Use this attribute
AFTER to get the correct value of automatically updated columns, such as time and date
UPDATE stamps.

REREAD Set to 1 to reread records from the database after inserting into it. Use this attribute
AFTER to get the correct value of automatically-updated columns, such as time and date
 SQLConnect 531

INSERT stamps.

DRV Use the DRV attribute for compatibility with Citect v2.01 and earlier. Use the
DRV instead of the data source name (DSN) in the connection string. Do not use
DRV in new Citect applications.

Citect recognises the above attributes for all the database systems in the table
below, but not all these attributes are essential for all databases. The asterisks
(*) beside each database indicate the attributes you must use to connect to that
database. The acceptable values for each attribute also vary according to the
database system, so select from the list to see the attributes and values:

DATABASE SYSTEM DSN UID PWD DRV

Btrieve Files * QEBTR

dBASE Files * QEDBF

EXCEL Files * QEXLS

IBM DB2 X X X QEDB2

Informix

INGRES * * QEING

Netware SQL * QEXQL

Oracle * * * QEORA

OS/2 and DB2/2 * * * QEEE

Paradox * * QEPDX

SQLBase/ (Gupta) * * * QEGUP

SQL Server * * * QESS

Text Files * * QETXT

XDB Databases * * * QEXDB

DRV .......... DRV names are included only for maintaining Citect applications
built using Citect v2.01 or earlier. For these early version, use DRV
instead of the data source name (DSN).
532 SQLConnect

X .... No longer supported directly. See information on the OS/2 and DB2/2
database drivers and the "Q+E Database Drivers Reference Manual".

Return Value The SQL connection handle if the connection is successful, otherwise -1 is returned. (For details
of the 307 error code, call the SQLErrMsg() function). The SQL connection handle identifies
the table where details of the associated SQL connection are stored.
Related Functions SQLBeginTran, SQLCommit, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec, SQLFieldInfo,
SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples
/* Make a connection to an SQL server and select the name field from
each record in the employee database. */
FUNCTION
ListNames()

INT hSQL;
STRING sName;
INT Status;

hSQL = SQLConnect("DSN=MyDatabase;UID=billw;SRVR=CI1");
IF hSQL <> -1 THEN
Status = SQLExec(hSQL, "SELECT NAME FROM EMPLOYEE");
IF Status = 0 THEN
WHILE SQLNext(hSQL) = 0 DO
sName = SQLGetField(hSQL, "NAME");
. . .
END
SQLEnd(hSQL);
ELSE
Message("Error", SQLErrMsg(), 48);
END
SQLDisconnect(hSQL);
ELSE
Message("Error", SQLErrMsg(), 48);
END
END

SQLDisconnect
Description Closes a database connection. You should close all connections to databases before you shut
down Citect, to release system resources.
For each active transaction (that is, for each SQLBeginTran() call), you should complete the
transaction before you disconnect from the databasecall SQLCommit() to save your changes,
or SQLRollBack() function to discard changes. If you call SQLDisconnect() while a transaction
 SQLDisconnect 533

is still active, Citect automatically "rolls back" the transactionany changes you made to the
database in that transaction are discarded.
Citect also automatically ends any queries that are active when the database is disconnected. If
you have called SQLExec() during a database connection, you must call SQLEnd() before you
disconnect from the database or the disconnection could fail.
Syntax SQLDisconnect(hSQL)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
You should not call SQLErrMsg() if SQLDisconnect() returns zero (that is, if the disconnection
is successful). SQLErrMsg() would provide information about a connection that does not exist
the information could be meaningless.
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLEnd, SQLErrMsg, SQLExec, SQLFieldInfo,
SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples See SQLConnect.

SQLEnd
Description Ends the execution of an SQL query (from the latest SQLExec() call). If you have called the
SQLExec() function from within a database connection, you should call SQLEnd() before you
disconnect from that database. When the SQLEnd() function ends the execution of the current
SQL query, it frees the memory that was allocated for that query.
Only one query can be active at a time, so you do not need to end one query before you execute
another queryeach time you call SQLExec(), the previous query (through a previous
SQLExec() call) is automatically ended. Similarly, Citect automatically ends the latest query
when it disconnects the database, even if you have not called SQLEnd(). However, the
SQLEnd() function ensures efficiencySQLEnd() releases the memory that was allocated when
the latest query was executed.
Syntax SQLEnd(hSQL)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.
534 SQLEnd

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange,
SQLRollBack, SQLTraceOff, SQLTraceOn
Examples See SQLConnect.

SQLErrMsg
Description Returns an error message from the SQL system. If a 307 error code occurs when one of the SQL
functions is called, an SQL error message is generated. Call this function to get that error
message.
Syntax SQLErrMsg()

Return Value The error message (as a string).

Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange,
SQLRollBack, SQLTraceOff, SQLTraceOn
Examples See SQLConnect.

SQLExec
Description Executes an SQL query on a database. With this function, you can execute any SQL query or
command supported by the SQL database. Only "CHAR" type fields are supported in database
tables.
Keywords such as "DATE", "TIME", and "DESC" cannot be used as field names by some
database systems. To use fields with these names, you must append underscores to the names
(e.g. "TIME_", "DATE_", "DESC_").
The SQLNext() function must be called after the SQLExec() function before you can access data
in the first record.
Only one query can be active at a time, so you do not need to end one query before you execute
another queryeach time you call SQLExec(), the previous query (through a previous
SQLExec() call) is automatically ended. Similarly, Citect automatically ends the latest query
when it disconnects the database, even if you have not called SQLEnd(). However, the
SQLEnd() function ensures efficiencySQLEnd() releases the memory that was allocated when
the latest query was executed.
Syntax SQLExec(hSQL, sSelect)
 SQLExec 535

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

sSelect..............The SQL query to be sent to the SQL database.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange,
SQLRollBack, SQLTraceOff, SQLTraceOn
Examples
These examples assume that the following tables are setup in a SQL server (with the name
configured in Windows Control Panel) and opened with the SQLConnect() function:
PEOPLE
SURNAME FIRSTNAME OCCUPATION DEPARTMENT

MARTIAN MARVIN ENGINEER MANAGEMENT

CASE CARRIE SUPPORT CITECT

LIGHT LARRY PROGRAMMER CITECT

BOLT BETTY ENGINEER SYSTEMS

PHONE

SURNAME NUMBER

MARTIAN 5551000

CASE 5551010

BOLT 5551020

LIGHT 5551030
Each SQL string (sSQL) should be encased within the SQLExec function, for example:

SQLExec(hSQL, sSQL);
536 SQLExec

To add a record to a table:

sSQL = "INSERT INTO PEOPLE (SURNAME, FIRSTNAME, OCCUPATION,

DEPARTMENT)
VALUES('ALLEN','MATTHEW','PROGRAMMER','CITECT')";
This SQL command changes the PEOPLE table to:
PEOPLE
SURNAME FIRSTNAME OCCUPATION DEPARTMENT

MARTIAN MARVIN ENGINEER MANAGEMENT

CASE CARRIE SUPPORT CITECT

LIGHT LARRY PROGRAMMER CITECT

BOLT BETTY ENGINEER SYSTEMS

ALLEN MATTHEW PROGRAMMER CITECT

To remove records from a table:

sSQL = "DELETE FROM (PEOPLE, PHONE) WHERE SURNAME='MARTIAN'";

SQLBeginTran(hSQL);
SQLExec(hSQL,sSQL);
IF (Message("Warning", "Do you really want to DELETE MARTIAN",
33) = 0) THEN
SQLCommit(hSQL);
ELSE
SQLRollback(hSQL);
END
Assuming that the OK button was pressed on the Message Box, the tables will be changed to:
PEOPLE
SURNAME FIRSTNAME OCCUPATION DEPARTMENT

CASE CARRIE SUPPORT CITECT

LIGHT LARRY PROGRAMMER CITECT

BOLT BETTY ENGINEER SYSTEMS

PHONE

SURNAME NUMBER
 SQLExec 537

CASE 5551010

BOLT 5551020

LIGHT 5551030
To change a record:

sSQL = "UPDATE PEOPLE SET OCCUPATION='SUPPORT' WHERE

FIRSTNAME='LARRY'";
This SQL command changes the PEOPLE table to:
PEOPLE
SURNAME FIRSTNAME OCCUPATION DEPARTMENT

MARTIAN MARVIN ENGINEER MANAGEMENT

CASE CARRIE SUPPORT CITECT

LIGHT LARRY SUPPORT CITECT

BOLT BETTY ENGINEER SYSTEMS

To select a group of records from a table:

sSQL = "SELECT SURNAME FROM PEOPLE WHERE OCCUPATION='ENGINEER'";

This SQL command will return the following table back to Citect. The table can then be
accessed by the SQLNext() function and the SQLGetField() functions.
CITECT TABLE for hSQL
SURNAME

MARTIAN

BOLT
You can also select data using a much more complete SQL string, for example:

sSQL = "SELECT (SURNAME, OCCUPATION, NUMBER) FROM (PEOPLE, PHONE)

WHERE DEPARTMENT='CITECT' AND PEOPLE.SURNAME =
PHONE.SURNAME";
This SQL command retrieves the following table:
SURNAME OCCUPATION NUMBER
538 SQLExec

CASE SUPPORT 5551010

LIGHT PROGRAMMER 5551030

To extract information from a table:

STRING sInfo[3][10]
int i = 0;

WHILE ((SQLNext(hSQL) = 0) and (i < 10)) DO

sInfo[0][i] = SQLGetField(hSQL, "SURNAME");
sInfo[1][i] = SQLGetField(hSQL, "OCCUPATION");
sInfo[2][i] = SQLGetField(hSQL, "NUMBER");
END
This code example leaves the information in the sInfo two dimensional array as follows:
sInfo
0 1 2

0 CASE SUPPORT 5551010

1 LIGHT PROGRAM 5551030

MER

...

SQLFieldInfo
Description Gets information about the fields or columns selected by a SQL query. The function returns the
name and width of the specified field. If you call the function within a loop, you can return the
names and sizes of all the fields in the database.
Keywords such as "DATE", "TIME", and "DESC" cannot be used as field names by some
database systems. To use fields with these names, you must append underscores to the names
(e.g. "TIME_", "DATE_", "DESC_").
Syntax SQLFieldInfo(hSQL, hField, sName, Width)
 SQLFieldInfo 539

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

hField ..............The field (or column) handle, indicating the position of the field in the database.

sName ..............A string variable in which the function stores the field name.

Width ...............An integer variable in which the function stores the field width.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples
! Lists all fields in the Employee database
FUNCTION
ListFields()

INT hSQL;
STRING sField;
INT Count;
INT Width;
INT Index;
SQLTraceOn("C:\DATA\TRACE.LOG");
hSQL = SQLConnect("DRV=QEDBF");

SQLExec(hSQL, "SELECT * FROM C:\DATA\EMPLOYEE");

Count = SQLNoFields(hSQL);
Index = 0;
WHILE Index < COUNT DO
SQLFieldInfo(hSQL,Index,sField,Width);
. . .
END
SQLEnd(hSQL);
SQLDisconnect(hSQL);
SQLTraceOff();
END

SQLGetField
Description Gets field or column data from a database record. To get the database record, use the SQLExec()
and SQLNext() functions.
540 SQLGetField

Keywords such as "DATE", "TIME", and "DESC" cannot be used as field names by some
database systems. To use fields with these names, you must append underscores to the names
(e.g. "TIME_", "DATE_", "DESC_").
Syntax SQLGetField(hSQL, sField)

hSQL ............... The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

sField...............The name of the field or column.

Return Value The field or column data (as a string). A null string is returned if the field or column does not
contain data.
The maximum length of the return data is 255 characters. If the returned data is longer than this,
the function will return error 306.
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLInfo, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples See SQLConnect.

SQLInfo
Description Gets information about a database connection.
Syntax SQLInfo(hSQL, Type)

hSQL ............... The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Type.................The type of information to get:

0 .... The connection string

1 .... The current SQL statement
2 .... The current database filename (only works with SQL device)
3 .... The SQL format handle
4 ..... The current Q+E library SQL handle. This handle can be used with
functions in the Q+E library which can be called in Cicode with the DLL
functions.
 SQLInfo 541

Return Value The information (as a string).

Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLNext, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples
SQLInfo(1,2);

SQLNext
Description Gets the next database record from an SQL query. Use the SQLExec() function to select a
number of records or rows from the SQL database, and then use the SQLNext() function to step
through each record separately.
Syntax SQLNext(hSQL)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNoFields, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples See SQLConnect.

SQLNoFields
Description Gets the number of fields or columns that were returned by the last SQL statement.
Syntax SQLNoFields(hSQL)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value The number of fields. A value of 0 is returned if no fields were returned or if an error has
occurred. (For details of an error, call the SQLErrMsg() function).
542 SQLNoFields

Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,

SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNumChange, SQLRollBack,
SQLTraceOff, SQLTraceOn
Examples See SQLFieldInfo.

SQLNumChange
Description Gets the number of records that were modified in the last SQL Insert, Update, or Delete
statement.
Syntax SQLNumChange(hSQL)

hSQL ............... The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value The number of records that were modified. A value of 0 is returned if no fields were returned or
if an error has occurred. (For details of an error, call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLRollBack, SQLTraceOff,
SQLTraceOn
Examples See SQLBeginTran.

SQLRollBack
Description Rolls back (discards) all changes made to the database within the current transaction. If you call
the SQLBeginTrans() function to begin a transaction, you are not committed to changes to the
database made by the Insert, Delete, and Update commands until you call the SQLCommit()
function. You can discard these changes by calling the SQLRollBack() function.
You can only call the SQLRollBack() function if you have called SQLBeginTran() to begin a
transaction. You do not need to begin a transaction to modify a database, but any changes you
make to a database outside of a transaction are automatically committed.
The SQLRollBack() function could affect different databases in different ways. If you have
difficulty using the function, check that your database is ODBC-compatible. Refer to the
documentation for your database for more information on rolling back transactions.
Syntax SQLRollBack(hSQL)
 SQLRollBack 543

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange,
SQLTraceOff, SQLTraceOn
Examples See SQLBeginTran.

SQLSet
Description Sets a statement string in the SQL buffer. Cicode cannot send an SQL statement that is longer
than 255 characters. If you have an SQL statement that is longer than the 255 character limit,
you can split the statement into smaller strings, and use this function and the SQLAppend()
function to append the statements in the SQL buffer.
Syntax SQLSet(hSQL, String)

hSQL................The handle to the SQL connection, returned from the SQLConnect() function.
The SQL connection handle identifies the table where details of the associated
SQL connection are stored.

String ...............The statement string to set in the SQL buffer. The string must contain the first
part of an SQL statement.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLAppend, SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd,
Examples
hSQL = SQLConnect("DRV=QEDBF");
SQLBeginTran(hSQL);
SQLSet(hSQL, "SELECT *")
SQLAppend(hSQL, " FROM EMP");
SQLAppend(hSQL, " ORDER BY last_name");
SQLExec(hSQL, "");
544 SQLTraceOff

SQLTraceOff
Description Turns off the debug trace. Use this function to stop tracing function calls that are made to the
database.
Syntax SQLTraceOff()

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange,
SQLRollBack, SQLTraceOn
Examples See SQLFieldInfo.

SQLTraceOn
Description Turns on a debug trace. Use this function to begin tracing function calls that are made to the
database. The information is written to a log file.
Syntax SQLTraceOn(sFile)

sFile................. The output file name for the debug trace.

Return Value 0 (zero) if successful, otherwise an error number is returned. (For details of the 307 error code,
call the SQLErrMsg() function).
Related Functions SQLBeginTran, SQLCommit, SQLConnect, SQLDisconnect, SQLEnd, SQLErrMsg, SQLExec,
SQLFieldInfo, SQLGetField, SQLInfo, SQLNext, SQLNoFields, SQLNumChange,
SQLRollBack, SQLTraceOff
Examples See SQLFieldInfo.

Sqrt
Description Gets the square root of a number.
Syntax Sqrt(Number)

Number............ Any positive number.

Return Value The square root of Number.

Related Functions Pow
 Sqrt 545

Examples
Variable=Sqrt(4);
! Sets Variable to 2.

StrClean
Description Removes control characters from a string. Any character that is not a displayable ASCII
character is removed from the string.
Syntax StrClean(String)

String ...............The source string.

Return Value The string with all control characters removed.

Related Functions StrTrim
Examples
Variable=StrClean("*****Text*****");
/* Sets Variable to "Text" (the "*" character in this example represents
an unprintable character). */

StrFill
Description Fills a string with a number of occurrences of another string.
Syntax StrFill(String, Length)

String ...............The string to be repeated.

Length..............The length of the string.

Return Value The filled string.

Related Functions StrPad
Examples
Variable=StrFill("abc",10);
! Sets Variable to "abcabcabca".

Variable=StrFill("x",10);
! Sets Variable to "xxxxxxxxxx".
546 StrFormat

StrFormat
Description Converts a variable into a formatted string. This function is the equivalent of the Cicode
" :#### " operator.
Syntax StrFormat(Variable, Width, DecPlaces, EngUnits)

Variable...........The variable to format into a string.

Width ...............The width of the variable after it has been converted to string format.

DecPlaces........The number of decimal places in the converted string.

EngUnits ......... The engineering units of the variable.

Return Value The variable (as a formatted string).

Related Functions StrToReal, StrToInt, RealToStr, IntToStr
Examples
Variable=StrFormat(10.345,5,2,"%");
! Sets Variable to "10.35%".

StrGetChar
Description Gets a single character from a string or buffer. Use this function to read a string, character by
character.
Syntax StrGetChar(String, iOffset)

String...............The source string.

iOffset .............. The offset in the string, commencing at 0.

Return Value The character at the offset in the string.

Related Functions StrSetChar
Examples
FOR i = 0 To length DO
char = StrGetChar(str, i);
! Get char from string
END
 StrLeft 547

StrLeft
Description Gets the left-most characters from a string.
Syntax StrLeft(String, N)

String ...............The source string.

N ......................The number of characters to get from the source string.

Return Value A string containing the left-most N characters of String.

Related Functions StrRight, StrMid, StrLength
Examples
Variable=StrLeft("ABCDEF",2);
! Sets Variable to "AB".

StrLength
Description Gets the length of a string.
Syntax StrLength(String)

String ...............The source string.

Return Value The length of the string (as an integer).

Related Functions StrRight, StrLeft, StrMid
Examples
Variable=StrLength("ABCDEF");
! Sets Variable to 6.

StrLower
Description Converts a string to lower-case.
Syntax StrLower(String)

String ...............The source string.

Return Value The string (as lower case).

Related Functions StrUpper
548 StrLower

Examples
Variable=StrLower("ABCDEF");
! Sets Variable to "abcdef".
Variable=StrLower("AbCdEf");
! Sets Variable to "abcdef".

StrMid
Description Gets characters from the middle of a string.
Syntax StrMid(String, Offset, Characters)

String...............The source string.

Offset ............... The offset in the string, commencing at 0.

Characters.......The number of characters to get, commencing at the offset.

Return Value A string containing the number of characters from the offset.
Related Functions StrLeft, StrRight, StrLength
Examples
Variable=StrMid("ABCDEF",1,3);
! Sets Variable to "BCD".
Variable=StrMid("ABCDEF",4,1);
! Sets Variable to "E".

StrPad
Description Pads a string with a number of occurrences of another string. Padding can be added to the left or
to the right of a string. If the string is already longer than the required string length, the string is
truncated.
Syntax StrPad(String, PadString, Length)

String...............The source string.

PadString ........The padding string.

Length .............The length of the string. If a positive length is specified, padding will be added
to the right of the string. If a negative length is specified, padding will be added
to the left of the string.
 StrPad 549

Return Value A padded string.

Related Functions StrFill
Examples
Variable=StrPad("Test"," ",10);
! Sets Variable to "Test ".
Variable=StrPad("Test","abc",-14);
! Sets Variable to "abcabcabcaTest".

StrRight
Description Gets the right-most characters from a string.
Syntax StrRight(String, N)

String ...............The source string.

N ......................The number of characters to get from the source string.

Return Value A string containing the right-most N characters of String.

Related Functions StrLeft, StrMid, StrLength
Examples
Variable=StrRight("ABCDEF",2);
! Sets Variable to "EF".

StrSearch
Description Searches for a string within a string, commencing at a specified offset. The result of the search
is the index in the source string, where the first character of the sub-string is found. Index 0 is
the first character in the string, index 1 is the second, etc.
Syntax StrSearch(Offset, String, Substring)

Offset ...............The offset in the string, commencing at 0.

String ...............The source string.

Substring..........The sub-string to search for.

Return Value The index in the search string, or -1 if the sub-string does not exist in the string.
Related Functions StrLength
550 StrSearch

Examples
Variable=StrSearch(1,"ABCDEF","CD");
! Sets Variable to 2.
Variable=StrSearch(4,"ABCDEF","CD");
! Sets Variable to -1.
Variable=StrSearch(5,"ABCDEF","F");
! Sets Variable to 5.

StrSetChar
Description Sets a single character into a string or buffer. Use this function to build up a string, character by
character, and terminate the string with the end-of-string character 0 (zero). (If you use a string
without a terminator in a function that expects a string, or in a Cicode expression, you could get
invalid results.) To use the string to build up a buffer, you do not need the terminating 0 (zero).
Syntax StrSetChar(sText, iOffset, Char)

sText ................ The destination string.

iOffset .............. The offset in the string, commencing at 0.

Char ................The ASCII character to set into the string.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions StrGetChar
Examples
! Set chars in buffer, Buf is NOT a valid string
! and cannot be used where a normal string would be used.
FOR i = 0 To length DO
StrSetChar(Buf, i, 30 + i);
END
StrSetChar(sStr, 0, 13); ! put CR into string
StrSetChar(sStr, 1, 0); ! terminate so may be used as a normal
string

StrToChar
Description Gets the ASCII code of the first character in a string.
Syntax StrToChar(String)

String...............The source string.

 StrToChar 551

Return Value The ASCII code of the first character in String.

Related Functions StrGetChar
Examples
Variable=StrToChar("ABC");
! Sets Variable to 65 (ASCII "A").

StrToDate
Description Converts a "date" string into a time/date variable. This variable is the same as returned from the
TimeCurrent() function. To set the order of the day, month, and year, and the delimiter, use the
Windows Control panel.
NOTE: Time/Date functions can only be used with dates between 1980 and 2035. You should check that the date
you are using is valid with the following Cicode:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax StrToDate(String)

String ...............The source string.

Return Value A time/date variable, or 274 if the time/date is out of range.

Related Functions StrToPeriod, StrToTime
Examples
! Australian format (dd/mm/yy) is set in the Windows Control panel.
DateVariable=DateAdd(StrToDate("3/11/95"),86400);
NewDate= TimeToStr(DateVariable, 2);
! Adds 24 hours to 3/11/95 and sets NewDate to "4/11/95".

StrToFmt
Description Converts a string into field data for a format template. This function is useful for breaking a
string into separate strings. After the string is converted, you can call the FmtGetField() function
to extract the individual data from the template fields.
Syntax StrToFmt(hFmt, String)
552 StrToFmt

hFmt ................ The format template handle, returned from the FmtOpen() function. The handle
identifies the table where all data on the associated format template is stored.

String...............The source string.

Return Value The string (formatted as template field data).

Related Functions FmtOpen, FmtGetField
Examples
StrToFmt(hFmt,"CV101 Raw Coal Conveyor");
Name=FmtGetField(hFmt,"Name");
! Sets Name to "CV101".

StrToGrp
Description Converts a string into a group and places it into a group number. Any existing values in the
group are cleared before the new values are inserted. The group string is a series of numbers
separated by " , " to list individual values or " .. " to specify a range of values.
Syntax StrToGrp(hGrp, Str)

hGrp ................ The group handle, returned from the GrpOpen() function. The group handle
identifies the table where all data on the associated group is stored.

Str....................The string to convert.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions GrpOpen
Examples
hGrp=GrpOpen("MyGrp",1);
! Set group to 1 ... 10 and 20, 30 and 40.
StrToGrp(hGrp,"1..10,20,30,40");

StrToHex
Description Converts a hexadecimal string into an integer. This function will search the string for the first
non-blank character, and then start converting until it finds the end of the string or a non-
hexadecimal numeric character. If the first non-blank character is not one of the following
hexadecimal characters, the return value is 0 (zero):
i) (0-9, a-f, A-F);
 StrToHex 553

ii) a space;
iii) a "+" (plus) or a "-" (minus) sign.
Syntax StrToHex(String)

String ...............The source string.

Return Value An integer (converted from String).

Related Functions StrToReal, StrToValue, HexToStr
Examples
Variable=StrToHex("123");
! Sets Variable to hex 123, decimal 291
Variable=StrToHex("F2");
! Sets Variable to hex F2, decimal 242
Variable=StrToHex("G45");
! Sets Variable to 0.
Variable=StrToHex("-FG");
! Sets Variable to hex, -F decimal -15.

StrToInt
Description Converts a string into an integer. This function will search the string for the first non-blank
character, and then start converting until it finds the end of the string or a non-numeric character.
If the first non-blank character is not a numeric character (0-9), a space, a " + " or a " - " sign, the
return value is 0 (zero).
Syntax StrToInt(String)

String ...............The source string.

Return Value An integer (converted from String).

Related Functions StrToReal, StrToValue
Examples
Variable=StrToInt("45");
! Sets Variable to 45.
Variable=StrToInt("45.23");
! Sets Variable to 45.
Variable=StrToInt("A45");
! Sets Variable to 0.
554 StrToLocalText

StrToLocalText
Description Converts a native string into the local version of that string. (The string must be contained
within quotation marks, as shown in the example below.) The local version is taken from the
current language database (as specified using the [Language]LocalLanguage parameter).
Syntax StrToLocalText(sText)

sText ................ The string for which you would like the local translation returned. This string
must be enclosed in quotation marks. For example:
"@(Motor Overload)"

Return Value The local version of the text if it was found, otherwise the native text or "#MESS" is returned,
depending on the setting of the [Language]DisplayError parameter.
Related Functions LanguageFileTranslate, SetLanguage.
Examples
StrToLocalText("@(Motor Overload)");
! Returns the Local translation of Motor Overload.

StrToPeriod
Description Converts a string into a time period. You would normally use this function to convert operator
input, e.g. to set a trend period.
Syntax StrToPeriod(String)

String...............The source string.

Return Value A period (converted from String).

Related Functions StrToTime, StrToDate
Examples
Variable=StrToPeriod("2");
! Sets Variable to 2 (seconds).
Variable=StrToPeriod("09:02");
! Sets Variable to 542 ((9*60)+2 seconds).
Variable=StrToPeriod("12:03:45");
! Sets Variable to 43425 ((12*60*60)+(3*60)+45 seconds).
 StrToReal 555

StrToReal
Description Converts a string into a floating-point number. This function will search the string for the first
non-blank character, and then start converting until it finds the end of the string or a non-numeric
character. If the first non-blank character is not a numeric character (0-9), a space, a decimal
point, a " + " or a " - " sign, the return value is 0 (zero).
Syntax StrToReal(String)

String ...............The source string.

Return Value A floating-point number (converted from String).

Related Functions StrToInt, StrToValue
Examples
Variable=StrToReal("45");
! Sets Variable to 45.
Variable=StrToReal("45.23");
! Sets Variable to 45.23
Variable=StrToReal("A45");
! Sets Variable to 0.

StrToTime
Description Converts a "time" string into a time/date variable. The value returned is the number of seconds
from midnight. You can add this value to the date to get the current time value. To set the time
delimiter use the Windows Control panel.
Syntax StrToTime(String)

String ...............The source string.

Return Value A time/date variable.

Related Functions Time, Date
Examples
Variable=StrToTime("11:43:00");
! Sets Variable to (11*3600+43*60+0) seconds.
Variable=StrToTime("9:02");
! Sets Variable to (9*3600+2*60) seconds.
Variable=StrToTime("2");
! Sets Variable to (2*3600) seconds.
556 StrToValue

StrToValue
Description Converts a string into a floating-point number. This function is similar to the StrToReal()
function except that the function halts if it is passed an empty or invalid string. The function will
search the string for the first non-blank character, and then start converting until it finds the end
of the string or a non-numeric character. If the first non-blank character is not a numeric
character (0-9), a space, a decimal point, a " + " or a " - " sign, the function will halt.
Use this function to check keyboard input from the operator by setting control points (e.g. it
prevents a setpoint from being set to 0 if the operator presses ENTER or enters invalid data by
mistake).
Syntax StrToValue(String)

String...............The source string.

Return Value A floating-point number (converted from String).

Related Functions StrToReal, StrToInt
Examples

System Keyboard
Key Sequence F3 ######## Enter

Command SP123 = StrToValue(Arg1);

Comment Set setpoint 123 to value unless value is

invalid

Note that the Cicode is halted. Any other Cicode after the StrToValue() function will not
execute.

StrTrim
Description Removes leading and trailing spaces from a string. Internal spaces are not removed from the
string.
Syntax StrTrim(String)

String...............The source string.

Return Value String with leading and trailing spaces removed.

Related Functions StrPad, StrFill
 StrTrim 557

Examples
Variable=StrTrim(" Test String ");
! Sets Variable to "Test String".

StrUpper
Description Converts a string to upper-case.
Syntax StrUpper(String)

String ...............The source string.

Return Value The string (as upper case).

Related Functions StrLower
Examples
Variable=StrUpper("abcdef");
! Sets Variable to "ABCDEF".
Variable=StrUpper("AbCdEf");
! Sets Variable to "ABCDEF".

StrWord
Description Gets the first word from a string. The word is removed from the string to allow the function to
be repeated. Word separators can be a space, newline, carriage return, or tab character.
Syntax StrWord(String)

String ...............The source string.

Return Value The first word from String (as a string).

Related Functions StrSearch
Examples
Str="THIS IS A STRING";
Variable=StrWord(Str);
! Sets Variable to "THIS".
Variable=StrWord(Str);
! Sets Variable to "IS".
Variable=StrWord(Str);
! Sets Variable to "A".
Variable=StrWord(Str);
! Sets Variable to "STRING".
558 SwitchConfig

SwitchConfig
Description Switches focus to a specific Citect configuration application. If the specified application is not
running, it will be started.
Syntax SwitchConfig(nApp)

nApp ................The configuration application:

1 ..... Citect Graphics Builder (CTDRAW32.EXE)

2 ..... Citect Project Editor (CTEDIT32.EXE)
3 ..... Citect Explorer (CTEXPLOR.EXE)
4 ..... Citect Cicode Editor (CTCICODE.EXE)

Return Value 0 (zero) if successful, otherwise an error is returned.

Examples
! Switch to the Graphics Builder.
SwitchConfig(1);

SysTime
Description Gets the Citect internal system millisecond counter. The counter is not based on any time, but
counts from 0 up to the maximum integer value and then back to 0.
You can use this function to time events down to the millisecond level, either by subtracting the
current SysTime from the SysTime at the start of the event, or by using the SysTimeDelta()
function (which will give the same result).
The SysTime() function does not return the time of day. Use the Time() or TimeCurrent()
function to obtain the time of day.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax SysTime()

Return Value The Citect internal system millisecond counter (as an integer).
 SysTime 559

Related Functions SysTimeDelta, Time, TimeCurrent

Examples
Start=SysTime();
! Gets the current time.
.
.
Delay=SysTime()-Start;
! Sets Delay to the time difference, in milliseconds.

SysTimeDelta
Description Calculates the time difference between a start time and the current time, and updates the start
time to the current time. You can time continuous events in a single operation. See the
SysTime() function for information on its use.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax SysTimeDelta(Start)

Start .................The start time returned from the SysTime() function.

Return Value The time difference from a start time and the current time.
Related Functions SysTime
Examples
Start=SysTime();
! Gets the current time.
.
.
Delay1=SysTimeDelta(Start);
! Sets Delay1 to the time difference from Start.
.
.
Delay2=SysTimeDelta(Start);
! Sets Delay2 to the time difference from the last SysTimeDelta() call.
560 TableLookup

TableLookup
Description Searches for a value in a table, and returns the position (offset) of the value in the table. Note
that the first item in a table is offset 0 (zero), the next item is offset 1, etc.
Syntax TableLookup(Table, Size, Value)

Table ...............The table to search. The table must be an array of real numbers.

Size ..................The maximum number of items in the table.

Value ...............The value to locate.

Return Value The offset to the table value, or -1 if the value does not exist.
Related Functions TableMath
Examples
REAL Levels[5]=10,15,50,100,200;
Variable=TableLookup(Levels,5,50);
! Sets Variable to 2.
Variable=TableLookup(Levels,5,45);
! Sets Variable to -1.

TableMath
Description Performs mathematical operations on a table of real (floating-point) numbers. This function
supports minimum, maximum, average, standard deviation, and total operations on a table of
values. Use this function for operating on tables returned from the trend system with the
TrnGetTable() function. You can set the Mode to either accept or ignore invalid or gated data
returned from TrnGetTable().
NOTE: This function cannot check the length of any arrays passed to it. If the array is shorter
than the size argument, unpredictable results can occur.
Syntax TableMath(Table, Size, Command, Mode)

Table ...............Any table of floating-point numbers.

Size ..................The maximum number of items in the table.

Command ........The mathematical operation to perform on the table:

0 .... Minimum
1 .... Maximum
 TableMath 561

2 .... Average
3 .... Standard deviation
4 .... Total

Mode................The mode of the operation:

0 .... Operate on all data

1 .... Ignore invalid or gated data returned from the TrnGetTable() function

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TableLookup TrnGetTable()
Examples
REAL Array[5]=10,15,50,100,200;
REAL Min,Avg;
! Get the minimum value.
Min=TableMath(Array, 5, 0, 0); ! Sets Min to 10.
! Get the average value.
Avg=TableMath(Array, 5, 2, 0); ! Sets Avg to 75.

TableShift
Description Shifts table items in a table by a number of positions. You can shift the table left or right. Items
shifted off the end of the table are lost. Items within a table that are not replaced by other items
(that have moved) are set to 0.
Syntax TableShift(Table, Size, Count)

Table................The table to shift, an array of real numbers.

Size ..................The maximum number of items in the table.

Count ...............The number of positions to shift the table items. A negative Count moves items
to the right and a positive Count moves items to the left.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TableMath, TableLookup
Examples
REAL Levels[5]=10,15,50,100,200;
TableShift(Levels,5,2);
/* Shifts the table items by 2 positions to the left, i.e.
Levels[0]=50
562 TableShift

Levels[1]=100
Levels[2]=200
Levels[3]=0
Levels[4]=0 */

TagDebug
Description Displays a dialog which allows you to select from a list of all the configured variable tags in
your system. Once you have selected a tag, you can either press the Read button to get the tag's
current value, or change the value by entering a new one, and pressing the Write button. This
function is useful for debugging or commissioning.
If you wish to read or change (write) the value of a particular element in an array variable, you
can just type it into the dialog's variable tag field as follows:

Syntax TagDebug()

Return Value The name of the tag entered in the dialog.

Related Functions TagInfo, TagRead, TagWrite
Examples
TagDebug(); /* Display debug form to allow user to debug */

TagInfo
Description Gets information about a variable tag. This function allows you to develop generic Cicode and
Super Genies.
Syntax TagInfo(sName, nType)

sName.............. The name of the tag from which to get information.

To get information on a particular element in an array, enter the array name here,
followed by the number of the element as follows:
 TagInfo 563

"PLC_Array[9]"

The above example tells the function to get information on the tenth element in
PLC_Array (remember, the address of the first element in an array is 0 (zero)).

nType ...............The type of information to get:

0 ..... The Tag name from the variables table. This is the same as sName
argument. (Returned to be compatible with the AssInfo() function).
1 ..... Engineering units
2 ..... Raw zero scale
3 ..... Raw full scale
4 ..... Engineering zero scale
5 ..... Engineering full scale
6 ..... Width of the format
7 ..... Number of decimal places of format.

Return Value The value of the information as a string.

Related Functions AssInfo, TagScaleStr
Examples
/* Get the engineering full scale value for the variable "PV131" */
EngFullScale = TagInfo("PV131", 5);
/* Get the engineering zero scale value for the array variable
"PLC_Array" */
EngZeroScale = TagInfo("PLC_Array", 4);

TagRamp
Description This function will increment a Tag by the amount defined by iPercentInc. It is often used for
incrementing a tag while a button is held down.
Syntax TagRamp(sTag, iPercentInc)

sTag .................The variable tag name (or alarm property name), as a string.

To read a particular element in an array, you can enter the array name here,
followed by an index to the element as follows:
"PLC_Array[9] "
564 TagRamp

The above example tells the function to read the 10th element in the array
variable PLC_Array (remember, the address of the first element in an array is 0
(zero)).
NOTE: .......If you enter an array offset using the nOffset argument, it will be
added to the index value specified here. For example,
TagRead("PLC_Array[9]", 4) will read the 14th element in
PLC_Array (because [9] means the 10th element, and an offset of 4
means 4 elements after the 10th = element 14).

iPercentInc ......The percentage by which you want to increase the value of the variable. A
negative number will decrease the variable. The increment is calculated as a
percentage of the full range.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TagInfo, TagRead, TagWrite.
Examples

Buttons
Text Ramp Up

Repeat Command TagRamp("PLC_VAR_1",2);

Comment Continual increment by 2%

TagRead
Description Reads a variable from the I/O Device. The variable tag must be defined in the Variable Tags
database. Because the variable tag is specified as a string (not as a tag), you can ignore the data
type of the variable.
This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
If you try to read many variables at the same time, the TagRead() function may be slow. The
offset index for array variables is checked against the size of the array.

NOTE: This function uses the format from the Variable Tag Database to format the resulting string. This m
means that if, for example, real_test = 12.345678, and is defined with format ##.##, ("real_test") will
return 12.35.

Syntax TagRead(sTag, nOffset)

 TagRead 565

sTag .................The variable tag name (or alarm property name), as a string.

To read a particular element in an array, you can enter the array name here,
followed by an index to the element as follows:
"PLC_Array[9] "
The above example tells the function to read the 10th element in the array
variable PLC_Array (remember, the address of the first element in an array is 0
(zero)).
NOTE:....... If you enter an array offset using the nOffset argument, it will be
added to the index value specified here. For example,
TagRead("PLC_Array[9]", 4) will read the 14th element in
PLC_Array (because [9] means the 10th element, and an offset of 4
means 4 elements after the 10th = element 14).

nOffset .............The offset for an array variable. This argument is optional - if not specified, it
has a default value of 0.

NOTE:....... If you enter an array index as part of the sTag argument, it will be
added to this offset value. For example, TagRead("PLC_Array[9]",
4) will read the 14th element in PLC_Array (because [9] means the
10th element, and an offset of 4 means 4 elements after the 10th =
element 14).

Return Value The value of the I/O Device variable, as a string. An error is returned if the tag does not exist, or
if the variable cannot be read from the I/O Device.
Related Functions TagWrite, IODeviceControl, IODeviceInfo
Examples
sValueVar1 = TagRead("PLC_VAR1");
sValueVarStr = TagRead("PLC_VAR_STR"); ! Read string data
/* Read the 15th element in array variable "PLC_Array" */
PLC_Array_15 = TagRead("PLC_Array[14]");

TagScaleStr
Description Gets the value of a tag at a specified scale. The value is returned as a formatted string using the
tags format specification and (optionally) the engineering units. Use this function to write
generic Cicode that will work with any type of tag. The variable tag must be defined in the
Variable Tags database.
Syntax TagScaleStr(sTag, Percent, EngUnits)

sTag .................The name of the tag.

566 TagScaleStr

Percent ............The percentage of full scale of the returned value.

EngUnits ......... Determines if the value is returned with engineering units:

0 ..... Do not return the value with engineering units

1 ..... Return the value with engineering units

Return Value The scale of the tag (as a string).

Related Functions TagInfo, TagRead, TagWrite, AssScaleStr
Examples
// Display the zero, 50% and full scale of the tag CV_123_PV
DspText(31,0,TagScaleStr("CV_123_PV", 0, 1));
DspText(32,0,TagScaleStr("CV_123_PV", 50, 1));
DspText(33,0,TagScaleStr("CV_123_PV", 100, 1));

TagWrite
Description Writes to an I/O Device variable by specifying the variable tag. The variable tag must be
defined in the Variable Tags database.
This function completes asynchronously to the caller. An error only occurs if the tag does not
exist. If the function fails to write to the I/O Device, a hardware error is generated.
Syntax TagWrite(sTag, sValue, nOffset)

sTag.................The variable tag name (or alarm property name), as a string.

To read a particular element in an array, you can enter the array name here,
followed by an index to the element as follows:
"PLC_Array[9] "
The above example tells the function to read the 10th element in the array
variable PLC_Array (remember, the address of the first element in an array is 0
(zero)).
NOTE: .......If you enter an array offset using the nOffset argument, it will be
added to the index value specified here. For example,
TagRead("PLC_Array[9]", 4) will read the 14th element in
PLC_Array (because [9] means the 10th element, and an offset of 4
means 4 elements after the 10th = element 14).

sValue..............The value to be written to the I/O Device variable. The value is specified as a
string. The function converts the string into the correct format, and then writes it
to the variable.
 TagWrite 567

To write to a particular element in an array, you can enter the array name here,
followed by an index to the element as follows:
"PLC_Array[9] "
The above example tells the function to write to the 10th element in the array
variable PLC_Array (remember, the address of the first element in an array is 0
(zero)).

NOTE:....... If you enter an array offset using the nOffset argument, it will be
added to the index value specified here. For example,
TagWrite("PLC_Array[9]", 24, 4) will set the 14th element in
PLC_Array to 24 (because [9] means the 10th element, and an offset
of 4 means 4 elements after the 10th = element 14).

nOffset .............The offset for an array variable.

NOTE:....... If you enter an array index as part of the sValue argument, it will be
added to this offset value. For example, TagWrite("PLC_Array[9]",
24, 4) will set the 14th element in PLC_Array to 24 (because [9]
means the 10th element, and an offset of 4 means 4 elements after
the 10th = element 14).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TagRead, IODeviceControl, IODeviceInfo
Examples
TagWrite("PLC_VAR1", 123);
TagWrite("PLC_VAR_STR", "string data to write");
TagWrite("PLC_ARRAY", 42, 3); ! Write to element 4 in array
TagWrite("PLC_Array[9]", 2); ! Write to element 12 in array

Tan
Description Calculates the trigonometric tangent of an angle.
Syntax Tan(Angle)

Angle................Any angle (in radians).

Return Value The tan of Angle.

Related Functions ArcTan
Examples
Variable=Tan(1);
568 Tan

! Sets Variable to 1.5574...

TaskGetSignal
Description Retrieves a value that indicates the signal that is currently set for a specific task. This function
can be used to check the value of the current signal before using TaskSetSignal to apply a new
signal.
Syntax TaskGetSignal(Hnd)

Hnd.................. The task's handle. To retrieve this use the function TaskHnd().

Return Value The value of the current signal. (0 (zero) represents normal operation, 1 indicates the task is
stopped).
Related Functions TaskSetSignal, TaskHnd, TaskKill, TaskNew, TaskResume

TaskHnd
Description Gets the task handle of a specific task. You can then use the task handle with other task
functions to control the task. If you do not specify a thread name, it will default to that of the
current task.
Syntax TaskHnd(sName)

sName.............. The thread name of the task. The thread name is the name of the function that
was passed to the TaskNew() function. For example, if. . .
TaskNew("MyTask","",0);
then. . .
hTask=TaskHnd("MyTask");
will return the handle of this task.
If you do not specify a thread name, it will default to that of the current task.

Return Value The task handle, identifying the table where all data on the task is stored.
Related Functions TaskKill, TaskNew, TaskResume, TaskSuspend
Examples
! Get the task handle of the current task and then kill it.
hTask=TaskHnd();
TaskKill(hTask);
 TaskHnd 569

! Get the task handle of MyTask and then kill it.

hTask=TaskHnd("MyTask");
TaskKill(hTask);

TaskKill
Description Kills a task. The Cicode task will be stopped and will not run again.
Syntax TaskKill(hTask)

hTask ...............The task handle, returned from the TaskNew() or TaskHnd() function. The task
handle identifies the table where all data on the associated task is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

NOTE: TaskKill is a very abrupt way to stop a Cicode task and has the potential to cause system
errors. A less hazardous method to stop a task is to use TaskGetSignal and TaskSetSignal.

Related Functions TaskGetSignal, TaskSetSignal, TaskHnd, TaskHnd, TaskNew, TaskResume, TaskSuspend

Examples
! Create a task, run it for 10 seconds and then kill it.
hTask=TaskNew("MyFunc","",0);
Sleep(10);
TaskKill(hTask);

FUNCTION
MyFunc()
INT Count;
WHILE 1 DO
Prompt("Hello "+Count:###);
Count=Count+1;
END
END

TaskNew
Description Creates a new Cicode task and returns the task handle. You pass the Name of the function (that
creates the task) as a string, not as the function tag, and pass all the arguments for that function in
Arg. After the task is created, it runs in parallel to the calling task. The new task will run
forever unless it returns from the function or is killed by another task.
You can set the Mode to run the task forever or only until the current page is changed or the
current window is freed. If you do not add 4 to the Mode, Citect starts the task immediately,
without reading any data from the I/O Devices - any I/O Device variable that you use will either
570 TaskNew

contain 0 (zero) or the last value read. If you add 4 to the Mode, Citect requests all I/O Device
data and waits for the data to be returned before starting the task - the task is provided with the
correct data, but there will be a delay in starting the task. Use Mode 4 when the I/O Device data
must be read, but do not use Mode 4 when the task has to start immediately.
It is also possible to specify that if the task is already running, the function will fail, and an error
will display. This is useful when you want only a single instance of the function running at any
point in time.
While a task runs, its copy of the I/O Device data is not refreshed, so if a task runs for a long
time, the data may become old. Use the ReRead() function to update the data (if required).
Any animation output for the new task is displayed in the window where it was created. If you
want to send output to other windows, use the WinSelect() function.
Syntax TaskNew(sName, sArg, Mode)

sName.............. The name of the function to create the task, as a string.

sArg .................The set of arguments to be passed to the function. Individual arguments must be
separated by commas (,). Enclose string arguments in quotes "" and use the
string escape character (^) around strings enclosed within a string. If you do not
enclose the string in quotes, then the string is only the first tag found. The entire
set of arguments must be enclosed in quotes ("").

Mode ...............The mode of the task:

0 .... Task runs forever.

1 .... Task runs until the current page is changed.
2 .... Task runs until the current window is freed.
4 .... Request all I/O Device data before starting task.
8 ..... If the task already exists, the function will fail.
You can add Mode 4 and Mode 8 to the other modes. For example, set Mode to
6 to request all I/O Device data before starting the task, and to run the task until
the current window is freed.

Return Value The task handle, or -1 if the task cannot be successfully created. The task handle identifies the
table where all data on the associated task is stored.
Related Functions TaskHnd, TaskKill, TaskResume, TaskSuspend, ReRead, WinSelect
Examples
! Create a task that displays a message for 10 seconds.
hTask=TaskNew("MyFunc","Data",0);
! Continue to run while task runs.
 TaskNew 571

FUNCTION
MyFunc(STRING Msg)
FOR I=0 TO 10 DO
Prompt(Msg);
Sleep(1);
END
END
.
.
! Call a function which expects more complex argument
hTask=TaskNew("ArgFunc","^"string one^",^"string two^",1,2",0);
hTask=TaskNew("ArgFunc","^""+sOne+"^",^""+sTwo+"^","+iOne:##+","+iTwo:##
,0);

FUNCTION
ArgFunc(STRING sOne, STRING sTwo, INT iOne, INT iTwo)
.
.
END

TaskResume
Description Resumes a task that was suspended by the TaskSuspend() function. After a task is resumed, it
runs on the next time-slice.
Syntax TaskResume(hTask)

hTask ...............The task handle, returned from the TaskNew() or TaskHnd() function. The task
handle identifies the table where all data on the associated task is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TaskHnd, TaskKill, TaskNew, TaskSuspend
Examples
TaskResume(hTask);

TaskSetSignal
Description Manually applies a signal to a specified task.
Syntax TaskSetSignal(Hnd, nSignal)

Hnd ..................The task's handle. To retrieve this use the function TaskHnd().
572 TaskSetSignal

nSignal ............Allows you to signal a specified task. Set to 0 (zero) for normal operation, 1 to
stop the task or any other number that represents a defined signal.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TaskGetSignal, TaskHnd, TaskKill, TaskNew, TaskResume

TaskSuspend
Description Suspends a task. The task will stop running and will start again only when TaskResume() is
called.
Syntax TaskSuspend(hTask)

hTask ...............The task handle, returned from the TaskNew() or TaskHnd() function. The task
handle identifies the table where all data on the associated task is stored.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TaskHnd, TaskKill, TaskNew, TaskResume
Examples
TaskSuspend(hTask);
.
.
TaskResume(hTask);

TestRandomWave
Description Generates a random wave. The height of the wave is restricted by minimum and maximum
values. You can offset the starting point of the wave, for example, to display multiple waves at
the same AN. You can use this function to generate test input.
Syntax TestRandomWave(Period, Low, High, Offset)

Period..............The number of seconds required to generate one cycle of the wave. If no period
is entered, the period has a default of 60.

Low..................The lowest value of the wave. If no low value is entered, this value has a default
of 0.

High.................The highest value of the wave. If no high value is entered, this value has a
default of 100.
 TestRandomWave 573

Offset ...............The offset in seconds, to generate the wave. If no offset is entered, the offset has
a default of 0.

Return Value The value of the random wave.

Related Functions TestSawWave, TestSinWave, TestSquareWave, TestTriangWave
Examples
/* Specify a random wave of 60 seconds duration, with a minimum value of
0 units and a maximum value of 100 units, with no offset. */
TestRandomWave(60,0,100,0);

TestSawWave
Description Generates a saw wave. The height of the wave is restricted by minimum and maximum values.
You can offset the starting point of the wave, for example, to display multiple waves at the same
AN. You can use this function to generate test input.
Syntax TestSawWave(Period, Low, High, Offset)

Period ..............The number of seconds required to generate one cycle of the wave. If no period
is entered, the period has a default of 60.

Low ..................The lowest value of the wave. If no low value is entered, this value has a default
of 0.

High.................The highest value of the wave. If no high value is entered, this value has a
default of 100.

Offset ...............The offset in seconds, to generate the wave. If no offset is entered, the offset has
a default of 0.

Return Value The value of the saw wave.

Related Functions TestRandomWave, TestSinWave, TestSquareWave, TestTriangWave
Examples
/* Specifies a saw wave of 60 seconds duration, with a minimum value of
0 units and a maximum value of 100 units, with no offset. */
TestSawWave();
574 TestSinWave

TestSinWave
Description Generates a sine wave. The height of the wave is restricted by minimum and maximum values.
You can offset the starting point of the wave, for example, to display multiple waves at the same
AN. You can use this function to generate test input.
Syntax TestSinWave(Period, Low, High, Offset)

Period..............The number of seconds required to generate one cycle of the wave. If no period
is entered, the period has a default of 60.

Low..................The lowest value of the wave. If no low value is entered, this value has a default
of 0.

High.................The highest value of the wave. If no high value is entered, this value has a
default of 100.

Offset ............... The offset in seconds, to generate the wave. If no offset is entered, the offset has
a default of 0.

Return Value The value of the sine wave.

Related Functions TestRandomWave, TestSawWave, TestSquareWave, TestTriangWave
Examples
/* Specifies a sine wave of 30 seconds duration, with a minimum value of
0 units and a maximum value of 100 units, with no offset. */
TestSinWave(30);

TestSquareWave
Description Generates a square wave. The height of the wave is restricted by minimum and maximum
values. You can offset the starting point of the wave, for example, to display multiple waves at
the same AN. You can use this function to generate test input.
Syntax TestSquareWave(Period, Low, High, Offset)

Period..............The number of seconds required to generate one cycle of the wave. If no period
is entered, the period has a default of 60.

Low..................The lowest value of the wave. If no low value is entered, this value has a default
of 0.

High.................The highest value of the wave. If no high value is entered, this value has a
default of 100.
 TestSquareWave 575

Offset ...............The offset in seconds, to generate the wave. If no offset is entered, the offset has
a default of 0.

Return Value The value of the square wave.

Related Functions TestRandomWave, TestSawWave, TestSinWave, TestTriangWave
Examples
/* Specifies a square wave of 30 seconds duration, with a minimum value
of -1000 units and a maximum value of 1000 units, with an offset of 10
seconds. */
TestSquareWave(30,-1000,1000,10);

TestTriangWave
Description Generates a triangular wave. The height of the wave is restricted by minimum and maximum
values. You can offset the starting point of the wave, for example, to display multiple waves at
the same AN. You can use this function to generate test input.
Syntax TestTriangWave(Period, Low, High, Offset)

Period ..............The number of seconds required to generate one cycle of the wave. If no period
is entered, the period has a default of 60.

Low ..................The lowest value of the wave. If no low value is entered, this value has a default
of 0.

High.................The highest value of the wave. If no high value is entered, this value has a
default of 100.

Offset ...............The offset in seconds, to generate the wave. If no offset is entered, the offset has
a default of 0.

Return Value The value of the triangular wave.

Related Functions TestRandomWave, TestSawWave, TestSinWave, TestSquareWave
Examples
/* Specifies a triangular wave of 60 seconds duration, with a minimum
value of 0 units and a maximum value of 100 units, with no offset. */
TestTriangWave();
576 Time

Time
Description Gets the current time in string format.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax Time(Format)

Format.............The format of the time:

0 .... Short time format, hh:mm

1 .... Long time format., hh:mm:ss
If omitted, the default Format is 0.

Return Value The current time (as a string).

Related Functions Date, TimeToStr
Examples
! If the current time is 10:45:30;
Variable=Time();
! Sets Variable to "10:45".
Variable=Time(0);
! Sets Variable to "10:45".
Variable=Time(1);
! Sets Variable to "10:45:30".

TimeCurrent
Description Gets the current system time/date in time/date variable format. Note that Citect stores time as
the number of seconds since 01/01/1970. You can convert this value into usable date and time
variables by using the various Date and Time functions.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
 TimeCurrent 577

.
ELSE
.
.
END
Syntax TimeCurrent()

Return Value A time/date variable.

Related Functions StrToDate, StrToTime
Examples
! If the current system time is 11:43:10 a.m.;
TimeVariable=TimeToStr(TimeCurrent(),0);
! Sets TimeVariable to "11:43".

TimeHour
Description Gets the hour value from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax TimeHour(Time)

Time.................The time/date variable.

Return Value The hour (as an integer).

Related Functions TimeCurrent
Examples
! If the current system time is 11:43:10 a.m.;
HoursVariable=TimeHour(TimeCurrent());
! Sets HoursVariable to 11.
578 TimeMidNight

TimeMidNight
Description Returns the number of seconds between midnight on January 1, 1970, and the midnight
immediately prior to the specified time/date. This function is useful for performing calculations
with the time and date.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax TimeMidNight(Time)

Time................. The time/date variable.

Return Value A time/date variable.

Related Functions TimeCurrent
Examples
timeNow = TimeCurrent();
! get the time variable at 7am today
time7am = TimeMidNight(timeNow) + 7*60*60;
IF timeNow > time7am AND timeNow < time7am + 10 THEN
Beep();
Prompt("Wake Up!");
END

TimeMin
Description Gets the minutes value from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
 TimeMin 579

Syntax TimeMin(Time)

Time.................The time/date variable.

Return Value The minute (as an integer).

Related Functions TimeCurrent
Examples
! If the current system time is 11:43:10 a.m.
MinutesVariable=TimeMin(TimeCurrent());
! Sets MinutesVariable to 43.

TimeSec
Description Gets the seconds value from a time/date variable.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax TimeSec(Time)

Time.................The time/date variable.

Return Value The second (as an integer).

Examples
! If the current system time is 11:43:10 a.m.;
SecondsVariable=TimeSec(TimeCurrent());
! Sets SecondsVariable to 10.

TimeSet
Description Sets the new system time. You can set the time only on the computer where this function is
called, or on the time server (and therefore on all Citect computers on the network).
580 TimeSet

When you change the time on the time server, the alarm, report, and trend servers must adjust
their databases records to the new time. Adjusting records can be time-consuming and can cause
some loss of data (if data logging is in progress). Change the time only if you must.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax TimeSet(Time, Mode)

Time................. The time/date variable to which the new time is set.

Mode ...............The mode of the set:

0 ..... Sets the time on this computer only. If this computer is a time server, the
time will be sent to all other Citect computers on the network.
1 ..... Set the time on this computer, and also send this time to the time server.
The time server will then send the new time to all other Citect computers on
the network.
2 ..... Get the time from the time server. The Time argument is ignored.
4 ..... Send this computer's time to the time server. The time server will then send
this time to all other Citect computers on the network. The Time argument
is ignored.

Return Value The error status of the set.

Related Functions TimeCurrent
Examples
! set the time to 11:43 on June 23 1993
time = StrToTime("11:43:00") + StrToDate("23/6/93");
TimeSet(time, 0);! sets the time on this computer only.
TimeSet(time, 1);! set the time on this computer and time server.
TimeSet(0, 2); ! Set the time on this computer from the time server.
TimeSet(0, 4); ! Send this computers time to the time server.
 TimeToStr 581

TimeToStr
Description Converts a time/date variable into a string. Use this function for calculating time differences or
run times, etc. Set Format to 6 to convert time periods that are in milliseconds, such as the times
that are returned from the SysTime() and SysTimeDelta() functions.
IMPORTANT: Time/Date functions can only be used with dates between 1980 and 2035. You
should check that the date you are using is valid with Cicode similar to the following:

IF StrToDat(Arg1)>0 THEN
.
.
ELSE
.
.
END
Syntax TimeToStr(Time, Format)

Time.................The time/date variable.

Format.............Format of the string:

0 .... Short time format, hh:mm.

1 .... Long time format, hh:mm:ss.
2 .... Short date format, dd/mm/yy.
3 .... Long date format, day month year.
4 .... Time and date, weekday month day year hh:mm:ss.
5 .... Long time period, hh:mm:ss. Time must be in seconds.
6 .... Millisecond time period, hh:mm:ss:xxx ("xxx" represents milliseconds).
Time must be in milliseconds.
7 .... Short time period, hh:mm. Time must be in seconds.
8 .... Long time period, days:hh:mm:sec. Time must be in seconds.
9 ..... Extended date format, dd/mm/yyyy.

Return Value A string containing the converted time/date variable.

Related Functions Time, TimeCurrent, Date
Examples
! If the current system time is 11:50:00 a.m.
String=TimeToStr(TimeCurrent(),0);
! Sets String to "11:50".
String=TimeToStr(125,5);
582 TimeToStr

! Sets String to "00:02:05".

Toggle
Description Toggles a digital tag on or off. If the variable tag is ON (1), this function will turn it OFF. If the
variable tag is OFF (0), this function will turn it ON.
Syntax Toggle(sTag)

sTag.................The digital tag to toggle.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Pulse
Examples

Buttons
Text Motor 145

Command Toggle(M145)

Comment Toggle the variable tag M145 (Motor

145) on or off

TraceMsg
Description Displays a message in the Kernel and Debugger debug windows.
Syntax TraceMsg(String)

String...............The message to display.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions DspKernel, KerCmd, DumpKernel, DebugBreak, Assert, DebugMsg, DebugMsgSet, CodeTrace,
ErrLog

Examples
TraceMsg("Error Found");
 TraceMsg 583

// Displays "Error Found" in the debug window

TrendDspCursorScale
Description Displays a scale value for the current pen in the current pen font.
Syntax TrendDspCursorScale(AN, Percent)

AN....................The AN number of the trend.

Percent ............The percentage of full scale to display for the current pen, as an integer.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue, TrendGetAn, TrendRun,
TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase, TrendZoom
Examples See in-built trend templates.

TrendDspCursorTag
Description Displays the trend tag name of the current pen in the pen font.
Syntax TrendDspCursorTag(AN)

AN....................The AN number of the trend.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTime, TrendDspCursorValue, TrendGetAn, TrendRun,
TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase, TrendZoom
Examples See in-built trend templates.

TrendDspCursorTime
Description Displays the cursor time of the current pen in the current pen font.
Syntax TrendDspCursorTime(AN, Format)

AN....................The AN number of the trend.

Format.............Format of the string:

584 TrendDspCursorTime

0 .... Short time format, hh:mm.

1 .... Long time format, hh:mm:ss.
2 .... Short date format, dd/mm/yy.
3 .... Long date format, day month year.
4 .... Time and date, weekday month day year hh:mm:ss.
5 .... Long time period, hh:mm:ss. Time must be in seconds.
6 .... Millisecond time period, hh:mm:ss:xxx ("xxx" represents milliseconds).
Time must be in milliseconds.
7 .... Short time period, hh:mm. Time must be in seconds.
8 .... Long time period, days:hh:mm:sec. Time must be in seconds.
9 ..... Extended date format, dd/mm/yyyy.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorValue, TrendGetAn, TrendRun,
TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase, TrendZoom
Examples See the in-built trend templates.

TrendDspCursorValue
Description Display the cursor value of the current pen in the current pen font.
Syntax TrendDspCursorValue(AN)

AN ...................The AN number of the trend.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendGetAn, TrendRun,
TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase, TrendZoom
Examples See in-built trend templates.

TrendGetAn
Description Gets the AN number of the trend beneath the current mouse position.
Syntax TrendGetAn()
 TrendGetAn 585

Return Value The AN of the trend, or 0 (zero) if the mouse is not positioned over a valid trend.
Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendRun, TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase,
TrendZoom
Examples See in-built trend templates.

TrendPopUp
Description Displays a pop-up trend with the specified trend pens. You must create the trend page with the
graphic builder and set all the pen names to blank.
Syntax TrendPopUp(sPage, sTag1. . .sTag8)

sPage ...............The name of the trend page (drawn with the Graphics Builder).

sTag1. . .sTag8 The trend tags to display on the page.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageTrend, TrendWin, WinNewAt
Examples

Buttons
Text Popup Trend
Command TrendPopUp("MyPop", "PV1", "PV2",
"PV3")

Comment Display a popup trend with three trend

pens

TrendRun
Description Initialises the cursor and rubber-band features on a trend page. This function is included as a
Cicode Object on all new trend pages. You should only use this function when configuring a
trend template that requires this functionality.
Syntax TrendRun(iPageType)

iPageType........The type of the page:

586 TrendRun

0 ..... Normal trend page template

1 ..... Compare trend page template

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase,
TrendZoom
Examples See in-built trend templates.

TrendSetDate
Description Sets the end date for all pens on a trend. Samples taken after this date will not be displayed.
You can enter the date in the Value argument, or leave the Value blank - a form is then displayed
in run time for the operator to enter an end date.
Syntax TrendSetDate(AN, Value)

AN ...................The AN number of the trend.

Value ...............The new date, as a string. Samples taken after date will not be displayed. This
argument is optional.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendRun, TrendSetScale, TrendSetSpan, TrendSetTime, TrendSetTimeBase,
TrendZoom
Examples See in-built trend templates.

TrendSetScale
Description Sets the scale of the current pen or of all pens on a trend. You can enter a scale in the Value
argument, or leave the Value blank - a form is then displayed in run time for the operator to enter
a value for the scale.
Syntax TrendSetScale(AN, Percent, Value)

AN ...................The AN number of the trend.

Percent ............The scale to be set:

 TrendSetScale 587

0 ..... Zero scale

100............. Full scale

Value................An optional value for the scale, as a string.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendRun, TrendSetDate, TrendSetSpan, TrendSetTime, TrendSetTimeBase,
TrendZoom
Examples See in-built trend templates.

TrendSetSpan
Description Sets the span time of the trend. The span time is the time period covered in the trend window.
You can enter a span time in the Value argument, or leave the Value blank - a form is then
displayed in run time for the operator to enter a value for the span time.
Syntax TrendSetSpan(AN, Value)

AN....................The AN number of the trend.

Value................An optional value for the span time, as a string.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendRun, TrendSetDate, TrendSetScale, TrendSetTime, TrendSetTimeBase,
TrendZoom
Examples See in-built trend templates.

TrendSetTime
Description Sets the end time for all the pens on a trend. Samples taken after this time will not be displayed.
You can enter an end time in the Value argument, or leave the Value blank - a form is then
displayed in run time for the operator to enter a value for the end time.
Syntax TrendSetTime(AN, Value)

AN....................The AN number of the trend.

588 TrendSetTime

Value ...............An optional value for the end time, as a string. Samples taken after this time will
not be displayed.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendRun, TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTimeBase,
TrendZoom
Examples See in-built trend templates.

TrendSetTimebase
Description Sets a new sampling period for a trend. You can enter a sampling period in the Value argument,
or leave the Value blank - a form is then displayed in run time for the operator to enter a value
for the sampling period.
Syntax TrendSetTimebase(AN, Value)

AN ...................The AN number of the trend.

Value ...............An optional value for the sampling period, as a string.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendRun, TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime,
TrendZoom
Examples See in-built trend templates.

TrendWin
Description Displays a trend page (in a new window) with the specified trend pens. You must create the
trend page with the graphic builder and set all the pen names to blank. You then display that
page by calling this function and pass the required trend tags. The function will create a new
window with the specified window mode.
Syntax TrendWin(sPage, X, Y, Mode, sTag1 . . .sTag8)

sPage...............The name of the trend page (drawn with the Graphics Builder).

X ......................The x pixel coordinate of the top left corner of the window.

Y ......................The y pixel coordinate of the top left corner of the window.

 TrendWin 589

Mode................The mode of the window:

0 ..... Normal page.

1 ..... Page child window. The window is closed when a new page is displayed,
e.g. when the PageDisplay() or PageGoto() function is called. The parent is
the current active window.
2 ..... Window child window. The window is closed automatically when the
parent window is freed with the WinFree() function. The parent is the
current active window.
4 ..... No re-size. The window is displayed with thin borders and no
maximise/minimise icons. The window cannot be re-sized.
8 ..... No icons. The window is displayed with thin borders and no
maximise/minimise or system menu icons. The window cannot be re-sized.
16... No caption. The window is displayed with thin borders, no caption, and no
maximise/minimise or system menu icons. The window cannot be re-sized.
32... Echo enabled. When enabled, all keyboard echo, prompts, and error
messages are displayed on the parent window. This mode should only be
used with child windows (e.g. Mode 1 and 2).
64... Always on top.
128 ........... Open a unique window. This mode prevents this window from
being opened more then once.
256............. Display the entire window. This mode ensures that no parts of the
window will appear off the screen
512............. Open a unique Super Genie. This mode prevents a Super Genie
from being opened more than once (at the same time). However, the
same Super Genie with different associations can be opened.
1024........... Disables dynamic resizing of the new window, overriding the setting
of the [Page]DynamicSizing parameter.
You can select multiple modes by adding modes together (for example, set Mode
to 9 to open a page child window without maximise, minimise, or system menu
icons).

sTag1 . . .sTag8 The trend tags to display on the page.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions PageTrend, TrendPopUp, WinNew
Examples
590 TrendWin

Buttons
Text Trend Window

Command TrendWin("MyTrend", 0, 0, 4, "PV1",

"PV2", "PV3")

Comment Display a trend page in a new window

with no maximise and minimise icons

TrendZoom
Description "Zooms" a specified trend in either one or both axes. Set the zoom values (TimeZoom and/or
ScaleZoom) to greater than one to "zoom in" or to less than one to "zoom out".
If you specify a destination AN, you can zoom one trend (at SourceAn) onto another (at DestAn),
in the same way as on the standard zoom trend page.
Syntax TrendZoom(SourceAn, TimeZoom, ScaleZoom, DestAn)

SourceAn .........The AN on which the source trend is located.

TimeZoom .......The scale by which the Time axis will be changed (as a real number).

ScaleZoom.......The scale by which the Scale axis will be changed (as a real number).

DestAn.............The AN on which the destination or target trend is located. If you do not enter a
DestAn, it is set to the same AN as SourceAn.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrendDspCursorScale, TrendDspCursorTag, TrendDspCursorTime, TrendDspCursorValue,
TrendGetAn, TrendRun, TrendSetDate, TrendSetScale, TrendSetSpan, TrendSetTime,
TrendSetTimeBase
Examples
TrendZoom(30, 2.0, 2.0);
/* Zoom in by a factor of 2 on both the time and scale axes. */
TrendZoom(30, 0.5, 0.5);
/* Zoom out by a factor of 2 on both the time and scale axes. */
 TrnAddHistory 591

TrnAddHistory
Description Adds an old (backed up) trend history file to the trend system so that its data can be used. When
you back-up your old trend files, rename them so that they do not clash with existing, active file
names. Your file names should show the age of the trend data in the file (e.g. month and year).
Citect determines the trend name from the header section of the specified file. The data in the
file is then added to the trend history.
This function can only be used at a Trends Server. However, a client can call this function
remotely by using the MsgRPC() function.
Syntax TrnAddHistory(FileName)

FileName .........The file name and directory path of an old history file.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnDelHistory, MsgRPC
Examples
TrnAddHistory("C:\CITECT\DATA\TR1_91.MAY");
! Adds the file to the trend system.

TrnClientInfo
Description Gets information about the trend that is being displayed at the AN point.
Syntax TrnClientInfo(hAn, Pen, Type, Data, Error)

hAn ..................The AN point number at which the trend is displayed.

Pen...................The trend pen number:

0 ..... The pen currently in focus

1...8. Pen1. . .Pen8

Type .................The type of information you would like returned.

1 ..... The number of samples configured for the trend. If you select Type 1, the
Data argument is ignored.

Data.................The Data argument is for future enhancements, and is currently ignored.

592 TrnClientInfo

Error ............... The Error argument is an output argument. If the function is successful, the error
is set to 0 (zero). If the function is unsuccessful, an error value is set, and a
hardware alarm is triggered.

Return Value The value (as a string) is returned if successful, otherwise a hardware alarm is generated.
Related Functions TrnInfo
Examples
INT nError;
INT nSamples;
INT nTime;
!Gets the number of samples configured for the current pen of the trend
displayed at AN 30.
nSamples = TrnClientInfo(30, 0, 1, "", nError);
IF nError = 0 THEN
nTime = nSamples * 50;
ELSE
nTime = 0;
END

TrnComparePlot
Description Prints two trends, one overlaid on the other. Each trend can have up to four tags configured on
it. The significance of this type of plot is that the two trends show different times and display
periods. It is possible to compare a trend tag or tags over different time slots. Each trend line is
drawn with a different pen style and marker as appropriate. The trend plot includes a comment
and a legend, and you can specify the vertical high and low scales.
For more advanced trend plotting, you can use the low-level plot functions.
Syntax TrnComparePlot(sPort, sTitle, sComment, iMode, nSamples, iTime1, rPeriod1, iTime2,
rPeriod2, Tag1......Tag8, rLoScale1, rHiScale1,......rLoScale8, rHiScale8)

sPort................The name of the printer port to which the plot will be printed. This name must
be enclosed within quotation marks. For example LPT1:, to print to the local
printer, or \\Pserver\canon1 using UNC to print to a network printer.

sTitle................ The title of the trend plot.

sComment........The comment that is to display beneath the title of the trend plot. You do not
have to enter a comment.

iMode ..............The colour mode of the printer.

0 ..... Black and White (default)

 TrnComparePlot 593

1 ..... Colour

nSamples..........The number of data points on the plot.

iTime1..............The end point in time (the most recent point) for the first trend.

rPeriod1 ..........The period (in seconds) of the first trend. This can differ from the actual trend
period.

If you do not enter a period, it defaults to the sample period of Tag1.

iTime2..............The end point in time (the most recent point) for the second trend.

rPeriod2 ..........The period (in seconds) of the second trend. This can differ from the actual trend
period.

If you do not enter a period, it defaults to the sample period of Tag5.

Tag1......Tag8...The trend tags for the plot. Tags 1 to 4 must be for the first trend, and tags 5 to 8
must be for the second.

rLoScale1, rHiScale1,......rLoScale8, rHiScale8 The minimum and maximum on the vertical

scale for the trend line of each of the tags (Tag1. . . Tag8).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnPlot, TrnPrint, PlotOpen SPCPlot
Examples
/* Prints two black and white trends (one overlaid on the other) to
LPT1, comparing the trend lines of one trend tag (Feed_Flow) at
different times. The first trend line has a starting time of 12noon, on
11/12/96, and the second has a starting time of 9am, on 11/10/96. Both
contain 200 sample points, and have a period of 2 seconds. Both trend
lines will be on a vertical scale of 10-100. */

INT Time;
INT RefTime;
Time = StrToDate("11/12/96") + StrToTime("12:00:00");
RefTime = StrToDate("11/10/96") + StrToTime("09:00:00");
TrnComparePlot("LPT1:","Citect Flow Comparison Plot","Comparison with
Reference",0,200,Time,2,RefTime,2,"Feed_Flow","","","","Feed_Flow","",""
,"",10,100,0,0,0,0,0,0,10,100);
594 TrnDelete

TrnDelete
Description Deletes a trend that is displayed on a current page. This trend may have been created by the
TrnNew() function or by a trend object.
Syntax TrnDelete(AN)

AN ...................The AN where the trend is located.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnNew
Examples
TrnDelete(20);
! Deletes the trend at AN20.

TrnDelHistory
Description Deletes a trend history file that has been added to the trend system by the TrnAddHistory()
function. This function does not delete the file, it only disconnects it from the historical trend
system.
This function can only be used at a Trends Server. However, a client can call this function
remotely by using the MsgRPC() function.
Syntax TrnDelHistory(FileName)

FileName.........The trend history file to disconnect from the historical trend system.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnAddHistory, MsgRPC
Examples
TrnDelHistory("C:\CITECT\DATA\TR1_91.MAY");
! Disconnects the file from the trend system.

TrnEcho
Description Enables and disables the echo of the trend display. Use this function when you need to make
many changes to a trend display, so that the display updates only once. You should first disable
the trend echo, do all the trend changes, and then enable the echo to show the changes.
Syntax TrnEcho(AN, nMode)
 TrnEcho 595

AN....................The animation number of the trend.

nMode..............The mode of the echo:

0 ..... Disable echo of the trend display.

1 ..... Enable echo of the trend display, to show changes.

Return Value The current echo mode, otherwise 0 (zero) is returned, and an error code is set. You can call the
IsError()function to get the actual error code.
Related Functions TrnSetScale, TrnSetPeriod
Examples
! Disable echo of trend display at AN40
TrnEcho(40,0);
! Change the scales on pens 1 and 2
TrnSetScale(40,1,0,-1000);
TrnSetScale(40,1,100,-1000);
TrnSetScale(40,2,0,-1000);
TrnSetScale(40,2,100,-1000);
! Enable echo to show changes to the display
TrnEcho(40,1);

TrnEventGetTable
Description Stores event trend data in an event table and the associated time stamp in a time table, for a
specified trend tag. Data is stored at the specified Period, working backwards from the starting
point specified by EventNo. If Period differs from the trend period configured in the Trend Tags
database, the values to be stored are calculated from the trend data. Values are either averaged
or interpolated.
This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
Syntax TrnEventGetTable(Tag, EventNo, Period, Length, Table, TimeTable, Mode)

Tag...................The trend tag.

EventNo ...........The starting event number for entries in the trend table. If EventNo is 0 (zero)
then the EventNo will be set to the current event number.

Period ..............The time difference between tabulated trend values (in seconds). For example, if
you set this period to 30 seconds, Citect will get the very last trend value
(sampled at the end of the trend section), then get the trend value that was
sampled 30 seconds before that, and so on until it reaches the start time of the
trend section.
596 TrnEventGetTable

If this period is different to the trend's sampling period, the trend values will be
averaged or interpolated. Set to 0 (zero) to default to the actual trend period.

Length .............The number of trend values to store in the trend table, from 1 to the maximum
number of items in the table.

Table ...............The Cicode array in which the trend data is stored. You can enter the name of an
array here (see the example).

TimeTable .......The table of integer values in which the time stamp is stored.

Mode ...............
BITS
Used for
0-1 Determines how invalid or gated trend values are processed
0 Invalid/Gated values are 0 (zero).
1 Invalid values are 0xFFFFBBBB; gated values are 0xFFFFAAAA.
2 Reverse the order of data in the table. Invalid/Gated values are 0 (zero).
3 Reverse the order of data in the table. Invalid values are 0xFFFFAAAA; gated
values are 0xFFFFBBBB.
NB These bits are not relevant to TrnSetDisplayMode().
2-6 The method of displaying the data when sample period is less than display period
(Condense modes).
0 Mean 3 – 31 Reserved
1 Minimum
2 Maximum
7-11 The method of displaying the data when sample period is not less than display period
(Stretch methods) AND subgroups are not being used.
0 Step 2. Actual Raw Samples
1 Ratio 3 – 31 Reserved
12-19 The number of samples that can be missing before a gap is displayed
20-31 Reserved

Return Value The actual number of samples read. The return value is 0 if an error occurs. You can call the
IsError()function to get the actual error code.
Related Functions TrnEventSetTable TrnGetEvent,
Examples
 TrnEventGetTableMS 597

TrnEventGetTableMS
Description Stores event trend data and time data (including milliseconds) for a specified trend tag. The
event trend data is stored in an event table, and the time stamp in time tables. Data is stored at
the specified Period, working backwards from the starting point specified by EventNo. If Period
differs from the trend period configured in the Trend Tags database, the values to be stored are
calculated from the trend data. Values are either averaged or interpolated.
This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
Syntax TrnEventGetTableMS(Tag, EventNo, Period, Length, Table, TimeTable, Mode,
MSTimeTable)

Tag...................The trend tag.

EventNo ...........The starting event number for entries in the trend table. If EventNo is 0 (zero)
then the EventNo will be set to the current event number.

Period ..............The time difference between tabulated trend values (in seconds). For example, if
you set this period to 30 seconds, Citect will get the very last trend value
(sampled at the end of the trend section), then get the trend value that was
sampled 30 seconds before that, and so on until it reaches the start time of the
trend section.

If this period is different to the trend's sampling period, the trend values will be
averaged or interpolated. Set to 0 (zero) to default to the actual trend period.

Length..............The number of trend values to store in the trend table, from 1 to the maximum
number of items in the table.

Table................The Cicode array in which the trend data is stored. You can enter the name of an
array here (see the example).

TimeTable........The table of integer values in which the time stamp is stored.

Mode................
BITS
Used for
0-1 Determines how invalid or gated trend values are processed
598 TrnEventGetTableMS

0 Invalid/Gated values are 0 (zero).

1 Invalid values are 0xFFFFBBBB; gated values are 0xFFFFAAAA.
2 Reverse the order of data in the table. Invalid/Gated values are 0 (zero).
3 Reverse the order of data in the table. Invalid values are 0xFFFFAAAA; gated
values are 0xFFFFBBBB.
NB These bits are not relevant to TrnSetDisplayMode().
2-6 The method of displaying the data when sample period is less than display period
(Condense modes).
0 Mean 3 – 31 Reserved
1 Minimum
2 Maximum
7-11 The method of displaying the data when sample period is not less than display period
(Stretch methods) AND subgroups are not being used.
0 Step 2. Actual Raw Samples
1 Ratio 3 – 31 Reserved
12-19 The number of samples that can be missing before a gap is displayed
20-31 Reserved

MSTimeTable .. The table of integer values in which the millisecond component of the time
stamp is stored.

Return Value The actual number of samples read. The return value is 0 if an error occurs. You can call the
IsError()function to get the actual error code.
Related Functions TrnEventSetTableMS TrnGetEvent, TrnEventGetTable
Examples

TrnEventSetTable
Description Sets event trend data in an event table, and the associated timestamp in a time table into the trend
system, for a specified trend tag. Data is set at the period specified, working backwards from the
starting point specified by EventNo.
If the period of setting data differs from the trend period (defined in the Trend Tags database),
the values to be set are calculated from the trend data, either averaged or interpolated. The user
must have the correct privilege (as specified in the Trend Tags form), otherwise the data is not
written.
 TrnEventSetTable 599

This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
Syntax TrnEventSetTable(Tag, EventNo, Period, Length, Table, TimeTable)

Tag...................The trend tag.

EventNo ...........The starting event number for entries in the trend table. If EventNo is 0 (zero)
then the EventNo will be set to the current event number.

Period ..............This will be the interval (in seconds) between trend values when they are set (i.e.
it will be the perceived sampling period for the trend). This period can differ
from the actual trend period. Set to 0 (zero) to default to the actual trend period.

Length..............The number of trend values in the trend table.

Table................The table of floating-point values in which the trend data is stored. You can
enter the name of an array here (see the example).

TimeTable........The table of integer values in which the time stamp is stored.

Return Value The actual number of samples read. The return value is 0 if an error occurs. You can call the
IsError() function to get the actual error code.
Related Functions TrnEventGetTable
Examples
REAL TrendTable1[100];
INT TimeTable[100];
/* Defines an array of a maximum of 100 entries. Assume that TrendTable1
has been storing data from a source. */
TrnEventSetTable("OP1",nEventNo, 1,10,TrendTable1[0], TimeTable[0]);
/* A set of 10 trend data values are set for the OP1 trend tag. */

TrnEventSetTableMS
Description Sets event trend data and time data (including milliseconds) for a specified trend tag. The event
trend data is set in an event table, and the time stamp in time tables. Data is set at the period
specified, working backwards from the starting point specified by EventNo.
If the period of setting data differs from the trend period (defined in the Trend Tags database),
the values to be set are calculated from the trend data, either averaged or interpolated. The user
must have the correct privilege (as specified in the Trend Tags form), otherwise the data is not
written.
600 TrnEventSetTableMS

This function is a blocking function. It blocks the calling Cicode task until the operation is
complete.
Syntax TrnEventSetTableMS(Tag, EventNo, Period, Length, Table, TimeTable, MSTimeTable)

Tag ..................The trend tag.

EventNo........... The starting event number for entries in the trend table. If EventNo is 0 (zero)
then the EventNo will be set to the current event number.

Period..............This will be the interval (in seconds) between trend values when they are set (i.e.
it will be the perceived sampling period for the trend). This period can differ
from the actual trend period. Set to 0 (zero) to default to the actual trend period.

Length .............The number of trend values in the trend table.

Table ...............The table of floating-point values in which the trend data is stored. You can
enter the name of an array here (see the example).

TimeTable .......The table of integer values in which the time stamp is stored.

MSTimeTable .. The table of integer values in which the millisecond component of the time
stamp is stored.

Return Value The actual number of samples read. The return value is 0 if an error occurs. You can call the
IsError() function to get the actual error code.
Related Functions TrnEventGetTable
Examples
REAL TrendTable1[100];
INT TimeTable[100];
/* Defines an array of a maximum of 100 entries. Assume that TrendTable1
has been storing data from a source. */
TrnEventSetTable("OP1",nEventNo, 1,10,TrendTable1[0], TimeTable[0]);
/* A set of 10 trend data values are set for the OP1 trend tag. */

TrnExportClip
Description Exports trend data to the Windows clipboard. The data is set at the specified Time and Period,
and listed from earliest to latest. Any gated or invalid data is written as 0.0.
Data is stored as a grid, with each row time-stamped. The first column/field is the date, followed
by the time, followed by the tags 1 to 8.
 TrnExportClip 601

You can use the ClipMode argument to make the output more useful. For example, to paste the
data into Excel, use ClipMode 2 for CSV format. If you use ClipMode 1 or 3, the default paste
menu option causes data to be pasted into the user’s spreadsheet as text. If you use ClipMode 3,
use the Paste Special option to paste the required format. (Note that not all packages support
multiple clipboard formats in this way.)
Syntax TrnExportClip(Time, Period, Length, Mode, ClipMode, sTag1, sTag2 ... sTag8)

Time.................The starting time for the data being exported.

Period ..............The period (in seconds) of the entries being exported. (This period can differ
from the actual trend period.)

Length..............The length of the data table, i.e. The number of rows of samples to be exported.
for example if you put the length as 12, and you declare two tags to be exported,
you get a grid with 12 rows of samples. Each row has values for each of the two
tags making a total of 24 samples in all.

Mode................The format mode to be used:

....... Periodic trends

1 ..... Export the Date and Time, followed by the tags.
2 ..... Export the Time only, followed by the tags.
4 ..... Ignore any invalid or gated values. (This mode is only supported for
periodic trends.)
8 ..... The time returned will have millisecond accuracy.
....... Event trends
1 ..... Export the Time, Date and Event Number, followed by the tags.
2 ..... Export the Time and Event Number, followed by the tags.
8 ..... The time returned will have millisecond accuracy.

ClipMode .........The format for the data being exported.

1 ..... Text
2 ..... CSV
You can add these modes for a combination of formats.

sTag1 ...............The trend tag names for the data being exported.

sTag2 ... sTag8 The trend tag names for the data being exported.

Return Value 0 (zero) if successful, otherwise an error is returned.

602 TrnExportClip

Related Functions ClipSetMode, TrnExportCSV

Examples
TrnExportClip(TimeCurrent(), 2, 60 * 60/2, 2, 3, "Feed", "Weight");
/* Export the last hour of data from the trend tags Feed and Weight to
the clipboard in both Text and CSV formats. Note that the 60 * 60/2 is a
decomposed way or writing 1800,
which is the number of 2 second samples in 1 hour. */

TrnExportCSV
Description Exports trend data to a file in CSV (Comma Separated Variable) format. The data is set at the
specified Time and Period, and listed from earliest to latest. Any gated or invalid data is written
as 0.0.
Data is stored as a grid, with each row time-stamped. The first column/field is the date, followed
by the time, followed by the tags 1 to 8.
You can view the CSV file with a text editor, and import the file directly into other packages
such as Excel for data analysis and presentation.
Syntax TrnExportCSV(Filename, Time, Period, Length, Mode, sTag1 ... sTag8)

Filename .........The name of the destination path and file.

Time................. The starting time for the data being exported.

Period..............The period (in seconds) of the entries being exported. (This period can differ
from the actual trend period.)

Length .............The length of the data table, i.e. The number of rows of samples to be exported.
for example if you put the length as 12, and you declare two tags to be exported,
you get a grid with 12 rows of samples. Each row has values for each of the two
tags making a total of 24 samples in all.

Mode ...............The format mode to be used:

....... Periodic trends

1 ..... Export the Date and Time, followed by the tags.
2 ..... Export the Time only, followed by the tags.
4 ..... Ignore any invalid or gated values. (This mode is only supported for
periodic trends.)
8 ..... The time returned will have millisecond accuracy.
 TrnExportCSV 603

....... Event trends

1 ..... Export the Time, Date and Event Number, followed by the tags.
2 ..... Export the Time and Event Number, followed by the tags.
8 ..... The time returned will have millisecond accuracy.

sTag1 ... sTag8 The trend tag names for the data being exported.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnExportDBF, TrnPrint
Examples
TrnExportCSV("c:\TrnData.CSV", TimeCurrent(), 2, 60 * 60/2, 2, "Feed",
"Weight");
/* Export the last hour of data from the trend tags Feed and Weight.
Note that the 60 * 60/2 is a decomposed way or writing 1800, which is
the number
of 2 second samples in 1 hour. */

TrnExportDBF
Description Exports trend data to a file in dBASE III format. The data is set at the specified Time and
Period, and listed from earliest to latest. Any gated or invalid data is written as 0.0.
Data is stored as a grid, with each row time-stamped. The first column/field is the date, followed
by the time, followed by the tags 1 to 8.
You can import the DBF file directly into other packages such as Excel, for data analysis and
presentation.
Syntax TrnExportDBF(Filename, Time, Period, Length, Mode, sTag1 ... sTag8)

Filename..........The name of the destination path and file.

Time.................The starting time for the data being exported.

Period ..............The period (in seconds) of the entries being exported. (This period can differ
from the actual trend period.)

Length..............The length of the data table, i.e. The number of rows of samples to be exported.
for example if you put the length as 12, and you declare two tags to be exported,
you get a grid with 12 rows of samples. Each row has values for each of the two
tags making a total of 24 samples in all.

Mode................The format mode to be used:

604 TrnExportDBF

....... Periodic trends

1 ..... Export the Date and Time, followed by the tags.
2 ..... Export the Time only, followed by the tags.
4 ..... Ignore any invalid or gated values. (This mode is only supported for
periodic trends.)
8 ..... The time returned will have millisecond accuracy.
....... Event trends
1 ..... Export the Time, Date and Event Number, followed by the tags.
2 ..... Export the Time and Event Number, followed by the tags.
8 ..... The time returned will have millisecond accuracy.

sTag1 ... sTag8 The trend tag names for the data being exported. Tag names longer than 10
characters will be truncated, as the standard DBF field format is 10 characters.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnExportCSV, TrnPrint
Examples
TrnExportDBF("c:\TrnData.DBF", TimeCurrent(), 2, 60 * 60/2, 2, "Feed",
"Weight");
/* Export the last hour of data from the trend tags Feed and Weight.
Note that the 60 * 60/2 is a decomposed way or writing 1800, which is
the number
of 2 second samples in 1 hour. */

TrnFlush
Description Writes acquired trend data to disk without waiting for the trend buffer to be filled. Citect
normally buffers the trend data in memory and only writes to disk when required, to give
optimum performance. Because this function reduces the performance of the Trends Server, use
it only when necessary.
Syntax TrnFlush(Name)

Name ............... The name of the logging tag. Set to " * " to flush all trend data.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnSetTable
Examples
 TrnFlush 605

TrnFlush("Trend1");
! Forces the Trend1 data to be written to disk.

TrnGetBufEvent
Description Gets the event number of a trend at an offset for a specified pen. This function only operates on
an event-based trend.
Syntax TrnGetBufEvent(AN, Pen, Offset)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Offset ...............The trend buffer offset, in samples. The number of samples can range from 0 to
the maximum number of samples that can display on the trend - 1.

Return Value The event number. If Offset is not within boundaries, 0 (zero) is returned. If AN or Pen is
invalid, 0 (zero) is returned and an error code is set.
Related Functions TrnGetEvent, TrnSetEvent, TrnGetCursorEvent
Examples
! For the trend at AN20
DspText(31,0,TrnGetBufEvent(20,0,10));
/* Displays the trend event at offset 10 for the pen currently in focus.
The event will display at AN31. */

TrnGetBufTime
Description Gets the time and date of a trend at an offset for a specified pen. The Offset should be a value
between 0 (zero) and the number of samples displayed on the trend.
Syntax TrnGetBufTime(AN, Pen, Offset)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8
606 TrnGetBufTime

Offset ............... The trend buffer offset, in samples. The number of samples can range from 0 to
the maximum number of samples that can display on the trend - 1.

Return Value A time/date variable. If Offset is not within boundaries, 0 (zero) is returned. If AN or Pen is
invalid, 0(zero) is returned and an error code is set.
Related Functions TrnGetCursorTime
Examples
! For the trend at AN20

INT time;
time = TrnGetBufTime(20,0,10);

IF time <> 0 THEN

DspText(31,0,TimeToStr(time,2));
END

/* Displays the trend date at offset 10 for the pen currently in focus.
The time will display at AN31. */

TrnGetBufValue
Description Gets the value of a trend at an offset for a specified pen. The offset should be a value between 0
(zero) and the number of samples displayed on the trend.
Syntax TrnGetBufValue(AN, Pen, Offset)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Offset ............... The trend buffer offset, in samples. The number of samples can range from 0 to
the maximum number of samples that can display on the trend - 1.

Return Value The trend value. If the actual value is not a valid value, the trend value is set to 0 (zero) and the
error "Trend data not valid" is set. If the actual value is a gated (not triggered) value, the trend
value is set to 0 (zero) and the error "Trend data is gated" is set. If Offset is not within
boundaries, 0 (zero) is returned. If AN or Pen is invalid, 0 (zero) is returned and an error code is
set.
Related Functions TrnGetCursorValue
Examples
 TrnGetBufValue 607

! For the trend at AN20

DspText(31,0,TrnGetBufValue(20,0,10):###.#);
/* Displays the trend value at offset 10 for the pen currently in focus.
*/

TrnGetCursorEvent
Description Gets the event number of a trend, at the trend cursor position for a specified pen. This function
only operates on an event-based trend.
Syntax TrnGetCursorEvent(AN, Pen)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value The event number, or 0 (zero) if the trend cursor is disabled.
Related Functions TrnSetEvent, TrnGetBufEvent, TrnGetEvent,
Examples
! For the trend at AN20
DspText(31,0,TrnGetCursorEvent(20,0));
/* Displays the trend event at the cursor for the pen currently in
focus. The event will display at AN31. */

TrnGetCursorMSTime
Description Gets the time (in milliseconds from the previous midnight) at a trend cursor for a specified pen.
Syntax TrnGetCursorMSTime(AN, Pen)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8
608 TrnGetCursorMSTime

Return Value The number of milliseconds since the previous midnight. If the trend cursor is disabled, 0 (zero)
is returned. If AN or Pen is invalid, 0 (zero) is returned and an error code is set.
Related Functions TrnGetCursorTime
Examples
! For the trend at AN20

STRING timeStr;
STRING msecStr;

timeStr = TimeToString(TrnGetCursorTime(20,1),2) + " ";

msecStr = TimeToString(TrnGetCursorMSTime(20,1),6);

DspText(31,0,timeStr + msecStr);

Returns
"23/02/01 10:53:22.717"

TrnGetCursorPos
Description Gets the offset of a trend cursor from its origin, in samples.
Syntax TrnGetCursorPos(AN)

AN ...................The AN where the trend is located.

Return Value The offset of a trend cursor from its origin, in samples, or -1 if the trend cursor is disabled.
Related Functions TrnSetCursorPos
Examples
! For the trend at AN20
! If the trend cursor is disabled
Offset=TrnGetCursorPos(20);
! Sets Offset to -1.

! If the trend cursor is 50 samples from the origin

Offset=TrnGetCursorPos(20);
! Sets Offset to 50.

TrnGetCursorTime
Description Gets the time and date at a trend cursor for a specified pen.
 TrnGetCursorTime 609

Syntax TrnGetCursorTime(AN, Pen)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value A time/date variable. If the trend cursor is disabled, 0 (zero) is returned. If AN or Pen is invalid,
0 (zero) is returned and an error code is set.
Related Functions TrnGetBufTime
Examples
! For the trend at AN20

INT time;
time = TrnGetCursorTime(20,1);

DspText(31,0,TimeToStr(time,2));
! Displays the trend cursor date for Pen1.

DspText(32,0,TimeToStr(time,1));
! Displays the trend cursor time for Pen1.

TrnGetCursorValue
Description Gets the value at a trend cursor for a specified pen.
Syntax TrnGetCursorValue(AN, Pen)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value The trend value. If the actual value is not valid, the trend value is set to 0 (zero) and the error
"Trend data not valid" is set. If the actual value is gated (not triggered), the trend value is set to
0 (zero) and the error "Trend data is gated" is set. If AN or Pen is invalid, 0(zero) is returned and
an error code is set.
Related Functions TrnGetBufValue
610 TrnGetCursorValue

Examples
! For the trend at AN20
DspText(31,0,TrnGetCursorValue(20,0));
! Displays the value at the trend cursor for the focus pen.

TrnGetCursorValueStr
Description Gets the value at a trend cursor for a specified pen. The value is returned as a formatted string
using the pen's format specification and (optionally) the engineering units.
Syntax TrnGetCursorValueStr(AN, Pen, EngUnits)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

EngUnits ......... Engineering units mode:

0 .... Do not include the engineering units at the end of the formatted string.
1 .... Include the engineering units at the end of the formatted string.

Return Value The trend value (as a string). If trend data is invalid, or an argument passed to the function is
invalid "<na>" is returned. If the actual value is gated (not triggered) "<gated>" is returned. If
the trend cursor is disabled, an empty string is returned.
Related Functions TrnGetCursorValue
Examples
! For the trend at AN20
DspText(31,0,TrnGetCursorValueStr(20,0,1));
/* Displays the value at the trend cursor for the focus pen. The value
will display as a formatted string (including the engineering units).*/

TrnGetDefScale
Description Gets the default engineering zero and full scales of a trend tag.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax TrnGetDefScale(Tag, LoScale, HiScale)
 TrnGetDefScale 611

Tag...................The trend tag.

LoScale ............The engineering zero scale.

HiScale ............The engineering full scale.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetScale, TrnInfo
Examples
REAL LoScale;
REAL HiScale;
TrnGetDefScale("PV1",LoScale,HiScale);
/* Returns engineering zero and full scales of the trend tag "PV1". */

TrnGetDisplayMode
Description Returns the display mode of the selected trend pen.
Syntax TrnGetDisplayMode(An, PenNumber)

An ....................The An of the chosen trend.

PenNumber......The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value An integer representing the trend's Display Mode.

Related Functions TrnSetDisplayMode
Examples
int DisplayMode = TrnGetDisplayMode (10, 7)
/* Returns The Display Mode of pen 7 for the trend at AN 10.*/

TrnGetEvent
Description Gets the event number of the trend at a percentage along the trend, using the current event as the
base point. This function only operates on an event-based trend. The first recorded event (the
start event) would be event number 1 and the highest number would be the latest event. The
event number is stored in a LONG and would eventually wrap around if you have enough events.
612 TrnGetEvent

Syntax TrnGetEvent(AN, Pen, Percent)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Percent ............The percentage of the trend from the starting event, from 0 (the start event) to
100 (the end event).

Return Value The event number.

Related Functions TrnSetEvent, TrnGetBufEvent, TrnGetCursorEvent
Examples
/* Display the start event for the current pen of the trend at AN20. */
DspText(31,0,TrnGetEvent(20,0,0));

TrnGetFormat
Description Gets the format of a trend tag being plotted by a specified pen.
Syntax TrnGetFormat(AN, Pen, Width, DecPlaces)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Width ...............The width of the format.

DecPlaces........The number of decimal places in the format.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetScale TrnGetUnits
Examples
/* If the trend tag being plotted by Pen1 of the trend at AN20 has a
format of "###.#" */
TrnGetFormat(20,1,Width,DecPlaces);
 TrnGetFormat 613

! Sets Width to 5 and DecPlaces to 1.

TrnGetGatedValue
Description Returns the internally stored value for <GATED>. If the internally stored value changes in the
future, you will not need to modify your Cicode, as this function ensures the return of the correct
value.
Syntax TrnGetGatedValue()

Return Value The internally stored value for <GATED>.

Related Functions TrnGetInvalidValue, TrnIsValidValue
Examples
MyTrendValue REAL;
IF MyTrendValue = TrnGetGatedValue THEN
Prompt ("This value is <GATED>")
ELSE IF MyTrendValue = TrnGetInvalidValue THEN
Prompt("This value is <TRN_NO_VALUES>")
ELSE
Prompt("Trend value is = " + RealToStr(MyTrendValue)
ENDIF

TrnGetInvalidValue
Description Returns the internally stored value for <INVALID>. If the internally stored value changes in the
future, you will not need to modify your Cicode, as this function ensures the return of the correct
value.
Syntax TrnGetInvalidValue()

Return Value The internally stored value for <INVALID>.

Related Functions TrnGetGatedValue, TrnIsValidValue
Examples
! TrnIsValidValue() example

REAL newArray[100];
REAL oldArray[90];
INT trigger;

INT
FUNCTION
DoubleArray()
614 TrnGetInvalidValue

INT i;

FOR i = 0 to 99 DO
IF TrnIsValidValue(oldArray[i]) = 1 OR trigger = 0 THEN
newArray[i] = TrnGetGatedValue();
ELSE IF i >= 90 OR TrnIsValidValue(oldArray[i]) = 2 THEN
newArray[i] = TrnGetInvalidValue();
ELSE
newArray[i] = oldArray[i] * 2;
END END
END

RETURN i;
END

TrnGetMode
Description Gets the trend display mode (real-time or historical trending).
Syntax TrnGetMode(AN, Pen)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value The trend display mode, 0 for real-time or 1 for historical.
Related Functions TrnScroll
Examples
! For the trend at AN20
INT Mode;
Mode=TrnGetMode(20,0);
! Gets the display mode of the pen in focus.
IF Mode=0 THEN
DspText(31,0,"Real Time Trending");
ELSE
DspText(31,0,"Historical Trending");
END
 TrnGetMSTime 615

TrnGetMSTime
Description Gets the time (in milliseconds from the previous midnight) of the trend (plotted by a specified
pen) at a percentage along the trend, using the time and date of the right-most sample displayed.
The time associated with the right-most sample displayed is known as the end time. The start
time is the time of the left-most sample displayed. Percent 0 (zero) will correspond to the end
time, and Percent 100 will correspond to the start time
100 % 0%

start time end time

.
Syntax TrnGetMSTime(AN, Pen, Percent)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Percent ............The percentage of the trend from the time and date of the right-most sample
displayed (end time), from 0 to 100.

Return Value The number of milliseconds since the previous midnight. 0(zero) is returned if an error occurs.
Related Functions TrnGetTime
Examples
! For Pen 1 at AN20
STRING timeStr;
STRING msecStr;
timeStr = TimeToString(TrnGetTime(20,1,100),2) + " ";
msecStr = TimeToString(TrnGetMSTime(20,1,100),6);
DspText(31,0,timeStr + msecStr);
616 TrnGetMSTime

Returns
"23/02/01 10:53:22.717"

TrnGetPen
Description Gets the trend tag being plotted by a specified pen.
Syntax TrnGetPen(AN, Pen)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value The trend tag (as a string) being plotted by Pen. If AN or Pen is invalid, an empty string is
returned, and an error code is set. You can call the IsError()function to get the actual error code.
Related Functions TrnSetPen
Examples
! For the trend at AN20
DspText(31,0,TrnGetPen(20,0));
! Displays the trend tag being plotted by the focus pen.

TrnGetPenFocus
Description Gets the number of the pen currently in focus.
Syntax TrnGetPenFocus(AN)

AN ...................The AN where the trend is located.

Return Value The pen currently in focus (between 1 and 8). If AN is invalid, -1 is returned and an error code is
set
Related Functions TrnSetPenFocus
Examples
! For the trend at AN20
DspText(31,0,TrnGetPenFocus(20));
! Displays the pen currently in focus.
 TrnGetPenNo 617

TrnGetPenNo
Description Gets the pen number of a pen name. The pens on a trend are either defined in the Page Trends
database or set by the TrnSetPen() function.
Syntax TrnGetPenNo(AN, Tag)

AN....................The AN where the trend is located.

Tag...................The trend tag.

Return Value The pen number, or 0 (zero) if an error occurs.

Related Functions TrnSetPen
Examples
/* Assume that 8 trend fonts, Pen1TrendFont ... Pen8TrendFont are
defined in the Fonts database. The following code will display the trend
tag using the matching font for that pen. */
! For the trend at AN20

STRING sFont;
INT iPen;

iPen = TrnGetPenNo(20,"PV1");

IF 0 < iPen AND iPen < 9 THEN

sFont = "Pen" + IntToStr(iPen) + "TrendFont";
DspStr(31,sFont,"PV1");
END

TrnGetPeriod
Description Gets the current display period of a trend. (To obtain the Sampling Period, use the TrnInfo
function.)
Syntax TrnGetPeriod(AN)

AN....................The AN where the trend is located.

Return Value The current display period of a trend (in seconds), or 0 (zero) if an error occurs.
Related Functions TrnSetPeriod, TrnInfo
Examples
/* For the trend at AN20, get and display the current display period. */
618 TrnGetPeriod

! If the period is 10 seconds

INT Period;
STRING Str;

Period=TrnGetPeriod(20);
Str=TimeToStr(Period,5);
DspStr(31,"",Str);

TrnGetScale
Description Gets the display scale of the trend tag being plotted by a specified pen.
Syntax TrnGetScale(AN, Pen, Percent)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Percent ............The percentage of the full scale, from 0 to 100.

Return Value The scale of the trend tag being plotted by Pen. If AN or Pen is invalid, 0(zero) is returned and
an error code is set.
Related Functions TrnSetScale, TrnGetDefScale
Examples
! For the trend at AN20
DspText(31,0,TrnGetScale(20,0,0));
! Displays the zero scale of the focus pen.

DspText(32,0,TrnGetScale(20,0,50));
! Displays the 50% scale of the focus pen.

DspText(33,0,TrnGetScale(20,0,100));
! Displays the full scale of the focus pen.

TrnGetScaleStr
Description Gets the scale of the trend tag being plotted by a specified pen. The value is returned as a
formatted string using the pen's format specification and (optionally) the engineering units.
Syntax TrnGetScaleStr(AN, Pen, Percent, EngUnits)
 TrnGetScaleStr 619

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Percent ............The percentage of the full scale, from 0 to 100.

EngUnits..........Engineering units mode:

0 .... Do not include the engineering units at the end of the formatted string.
1 .... Include the engineering units at the end of the formatted string.

Return Value The scale of the trend tag being plotted by Pen (as a string). If AN or Pen is invalid, <na> is
returned and an error code is set.
Related Functions TrnGetScale
Examples
! For the trend at AN20
DspText(31,0,TrnGetScaleStr(20,0,0,1));
/* Displays the zero scale of the focus pen. The scale displays as a
formatted string (including the engineering units). */
DspText(32,0,TrnGetScaleStr(20,2,50,1));
/* Displays the 50% scale of Pen2. The scale displays as a formatted
string (including the engineering units). */
DspText(33,0,TrnGetScaleStr(20,0,100,0));
/* Displays the full scale of the trend tag being plotted by the focus
pen. The scale displays as a formatted string (excluding the
engineering units). */

TrnGetSpan
Description Gets the span time of a trend (if the span was set by the TrnSetSpan() function). The span time
is the total time displayed in the trend window.
NOTE: If you call the TrnSetPeriod() function after the TrnSetSpan() function, the span is
automatically set to 0 (zero).
Syntax TrnGetSpan(AN)

AN....................The AN where the trend is located.

Return Value The span time, in seconds. 0(zero) is returned if the AN is invalid or if the span was not set by
the TrnSetSpan() function.
620 TrnGetSpan

Related Functions TrnSetSpan, TrnGetPeriod, TrnSetPeriod

Examples
// Use a keyboard command or button to set a span of 2 hours.
TrnSetSpan(40,StrToTime("2:00:00");

// Then use TrnGetSpan function to display the span

Time = TrnGetSpan(40)
DspText(31,0,TimeToStr(Time,5));

TrnGetTable
Description This function allows you to tabulate values from a specific section of trend. The values in the
table (possibly an array variable) are arranged by time, with the end time (specified by Time) at
the top, and the start time at the bottom.
If the period (Period) is different to the trend's sampling period (configured in the Trend Tags
database), values are either averaged or interpolated. If a mixture of gated data, valid data, and
no data is found, the valid data is averaged, and the other data is ignored.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax TrnGetTable(Tag, Time, Period, Length, Table, DisplayMode, Milliseconds)

Tag ..................The trend tag.

Time................. The end time and date (long integer) of the desired trend section. Once you have
entered the end time and date (Time), period (Period), and number of trend tag
values collected (Length), the start time and date will be calculated
automatically. For example, if Time = StrToDate("18/12/96") +
StrToTime("09:00"), Period = 30, and Length = 60, the start time would be
08:30. In other words, the trend values for the period between 8.30am and 9am
(on December 18, 1996) would be tabulated.

If Time is 0 (zero) then the Time will be set to the current time.

Period..............The time difference between tabulated trend values (in seconds). For example, if
you set this period to 30 seconds, Citect will get the very last trend value
(sampled at the end of the trend section), then get the trend value that was
sampled 30 seconds before that, and so on until it reaches the start time of the
trend section.
 TrnGetTable 621

If this period is different to the trend's sampling period, the trend values will be
averaged or interpolated. Set to 0 (zero) to default to the actual trend period.

Length..............The number of trend values to store in the trend table, from 1 to the maximum
number of items in the table.

Table................The Cicode array in which the trend data is stored. You can enter the name of an
array here (see the example).

DisplayMode ...
BITS
Used for
0-1 Determines how invalid or gated trend values are processed
0 Invalid/Gated values are 0 (zero).
1 Invalid values are 0xFFFFBBBB; gated values are 0xFFFFAAAA.
2 Reverse the order of data in the table. Invalid/Gated values are 0 (zero).
3 Reverse the order of data in the table. Invalid values are 0xFFFFAAAA; gated
values are 0xFFFFBBBB.
NB These bits are not relevant to TrnSetDisplayMode().
2-6 The method of displaying the data when sample period is less than display period
(Condense modes).
0 Mean 3 – 31 Reserved
1 Minimum
2 Maximum
7-11 The method of displaying the data when sample period is not less than display period
(Stretch methods) AND subgroups are not being used.
0 Step 2. Actual Raw Samples
1 Ratio 3 – 31 Reserved
12-19 The number of samples that can be missing before a gap is displayed
20-31 Reserved

Milliseconds.....This argument allows you to set your sample request time with millisecond
precision. After defining the time and date in seconds with the Time argument,
you can then use this argument to define the milliseconds component of the time.

For example, if you wanted to request data from the 18/12/96, at 9am, 13
seconds, and 250 milliseconds you could set the Time and Milliseconds
arguments as follows:
Time = StrToDate("18/12/96") + StrToTime("09:00:13")
622 TrnGetTable

Milliseconds = 250
If you don't enter a Milliseconds value, it defaults to 0 (zero). There is no range
constraint, but as there are only 1000 milliseconds in a second, you should keep
your entry between 0 (zero) and 999.

Return Value The actual number of samples read. 0(zero) is returned if an error occurs. You can call the
IsError()function to get the actual error code.
Related Functions TrnSetTable
Examples
REAL TrendTable1[100];
/* Defines an array of a maximum of 100 entries in which the trend data
is stored. */

TrnGetTable("OP1",StrToDate("18/12/91")
+StrToTime("09:00"),2,10,TrendTable1[0],0);
/* Stores the values of trend tag "OP1" in Table TrendTable1. Data is
stored at the following times:

18/12/91 09:00:00 TrendTable1[0]

08:59:58 TrendTable1[1]
08:59:56 TrendTable1[2]
.
.

18/12/91 08:59:42 TrendTable1[9] */

Average=TableMath(TrendTable1[0],100,2);
/* Gets the average of the trend data. */

TrnGetTime
Description Gets the time and date of the trend (plotted by a specified pen) at a percentage along the trend,
using the time and date of the right-most sample displayed. The time associated with the right-
most sample displayed is known as the end time. The start time is the time of the left-most
sample displayed. Percent 0 (zero) will correspond to the end time, and Percent 100 will
correspond to the start time
 TrnGetTime 623

100 % 0%

start time end time

.
Syntax TrnGetTime(AN, Pen, Percent)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Percent ............The percentage of the trend from the time and date of the right-most sample
displayed (end time), from 0 to 100.

Return Value A time/date variable. 0(zero) is returned if an error occurs.

Related Functions TrnSetTime
Examples
! For the trend at AN20

DspText(31,0,TimeToStr(TrnGetTime(20,0,0),2));
! Displays the trend current date for the focus pen.

DspText(32,0,TimeToStr(TrnGetTime(20,0,0),1));
! Displays the trend current time for the focus pen.

DspText(33,0,TimeToStr(TrnGetTime(20,0,50),1));
! Displays the time 50% along the trend for the focus pen.
624 TrnGetUnits

TrnGetUnits
Description Gets the data units for the trend tag plotted by a specified Pen.
Syntax TrnGetUnits(AN, Pen)

AN ...................The AN where the trend is located.

Pen ..................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Return Value The data units for the trend tag plotted by Pen, otherwise an empty string is returned, and an
error code is set. You can call the IsError()function to get the actual error code.
Related Functions TrnGetFormat, TrnGetScale
Examples
! For the trend at AN20

DspText(31,0,TrnGetUnits(20,0));
! Displays the data units for the focus pen.

TrnInfo
Description Gets the configured values of a trend tag.
Syntax TrnInfo(Tag, Type)

Tag ..................The name of the trend tag (enclosed in quotation marks "").

Type.................The type of information required:

1 ..... Trend Type

2 ..... Sample Period (to obtain the Display Period, use the TrnGetPeriod
function)
3 ..... Trend File Name (without file extension)
4 ..... Area
5 ..... Privilege
6 ..... Current Event Number. Valid only for event type trends.
7 ..... Engineering Units.
 TrnInfo 625

Return Value The value (as a string), otherwise an empty string is returned, and an error code is set. You can
call the IsError()function to get the actual error code.
Examples
! Get the file name of trend tag LT131
sFileName = TrnInfo("LT131", 3);

TrnIsValidValue
Description Determines whether a logged trend value is:
<VALID> - an actual trend value;
<GATED> - if a periodic trend has a trigger condition, and that condition is FALSE, a standard
substitute (or GATED) value is logged instead of the actual value; or
<INVALID> - for some reason, no value was logged.
Syntax TrnIsValidValue(TrendValue)

TrendValue ......A trend value (of type REAL).

Return Value 0 for <VALID>

1 for <GATED>
2 for <INVALID>
Related Functions TrnGetGatedValue, GetInvalidValue
Examples
! TrnIsValidValue() example

REAL newArray[100];
REAL oldArray[90];
INT trigger;

INT
FUNCTION
DoubleArray()
INT i;

FOR i = 0 to 99 DO
IF TrnIsValidValue(oldArray[i]) = 1 OR trigger = 0 THEN
newArray[i] = TrnGetGatedValue();
ELSE IF i >= 90 OR TrnIsValidValue(oldArray[i]) = 2 THEN
newArray[i] = TrnGetInvalidValue();
ELSE
newArray[i] = oldArray[i] * 2;
END END
626 TrnIsValidValue

END

RETURN i;
END

TrnNew
Description Creates a new trend at run time. This function performs the same operation as an entry in the
Page Trends database. After the trend is created by the TrnNew() function, all the other trend
functions can access and control the trend.
Syntax TrnNew(AN, Trend, Tag1 ... Tag8)

AN ...................The AN where the bottom right-hand corner of the trend is located.

Trend ............... The trend definition number.

Tag1 ... Tag8 ...The trend tags.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnDelete
Examples
TrnNew(20,trn002,"PV1","OP1");

/* Creates a new trend at AN20 using trend definition 2, plotting "PV1"

on Pen1 and "OP1" on Pen2. */

TrnPlot
Description Prints the trend line of one or more trend tags. Each trend line is drawn with a different pen style
and marker as appropriate. The trend plot includes a comment and a legend, and you can specify
the vertical high and low scales. The Mode defines the colour mode of the printer. The default
mode is black and white.
For more advanced trend plotting, you can use the low-level plot functions.
Syntax TrnPlot(sPort, nSamples, iTime, rPeriod, sTitle, Tag1......Tag8, iMode, sComment, rLoScale1,
rHiScale1, ......rLoScale8, rHiScale8)

sPort................The name of the printer port to which the plot will be printed. This name must
be enclosed within quotation marks. For example LPT1:, to print to the local
printer, or \\Pserver\canon1 using UNC to print to a network printer.
 TrnPlot 627

nSamples..........The number of data points on the plot.

iTime................The end point in time (the most recent point) for the trend plot.

rPeriod ............The period (in seconds) of the trend plot. This can differ from the actual trend
period.

If you do not enter a period, it defaults to the sample period of Tag1.

sTitle ................The title of the trend plot.

Tag1......Tag8...The trend tags.

iMode...............The colour mode of the printer.

0 ..... Black and White (default)

1 ..... Colour

sComment ........The comment that is to display beneath the title of the trend plot. You do not
have to enter a comment.

rLoScale1, rHiScale1, ......rLoScale8, rHiScale8 The minimum and maximum on the vertical
scale for the trend line of each of the tags (Tag1. . . Tag8).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnComparePlot, TrnPrint, PlotOpen SPCPlot
Examples
/* Prints a black and white plot to LPT1, containing the trend lines of
two variable tags (PV1 & PV2). The trend lines have a starting time of
9am, on 11/10/96, 200 sample points, and a period of 2 seconds. The
trend line of PV1 will be on a vertical scale of 0-200, and PV2 will be
on a vertical scale of 0-400. */

INT time;
Time = StrToDate("11/10/96") + StrToTime("09:00:00");
TrnPlot("LPT1:",200,Time,2,"Citect Trend
Plot","PV1","PV2","","","","","","",0,"Process variable operation at
shutdown",0,200,0,400);

TrnPrint
Description Prints the trend that is displayed on the screen (at hAn). You can specify the trend title, the target
printer, whether to print in colour or black and white, and whether to display the Plot Setup form
when the function is called.
628 TrnPrint

Syntax TrnPrint(sPort, sTitle, hAn, iModeColour, iDisplayForm)

sPort................The name of the printer port to which the plot will be printed. This name must
be enclosed within quotation marks "". For example "LPT1:", to print to the
local printer, or "\\Pserver\canon1" using UNC to print to a network printer.

It is not necessary to enter a printer port. The first time the printer port is
omitted, you will be prompted to select one at the Printer Setup form. The
selection you make will then be used as the default.

sTitle................ The title to print at the top of the trend plot. If you do not specify a title in sTitle,
the page title will be used.

hAn ..................The AN where the trend plot is located.

iModeColour ...The colour mode of the printer.

-1.... Colour to be decided (Default). Citect refers to the

[GENERAL]PrinterColourMode parameter to determine print colour. If
there is no setting for this parameter, it will default to black and white.
0 ..... Black and White
1 ..... Colour

iDisplayForm ..Defines whether or not the Plot Setup form will display when the function is
called. This form allows you to enter the colour mode of the printer, and define
the printer setup etc. (See Printing Trend Data for more information on this
form.)

-1.... Citect refers to the [GENERAL]DisablePlotSetupForm parameter to

determine if the form will display.
0 ..... Do not display form
1 ..... Display form

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnPlot, TrnComparePlot, WinPrint SPCPlot
Examples
TrnPrint("LPT1:","Test Print",40,0,0);
/* Prints the trend plot displayed at AN40, without prompting for setup
details.*/
 TrnSamplesConfigured 629

TrnSamplesConfigured
Description Gets the number of samples configured for the currently displayed trend.
Syntax TrnSamplesConfigured(AN)

AN....................The AN where the trend is located.

Return Value The number of samples configured for the trend, or 0 (zero) if an error occurs. You can call the
IsError()function to get the actual error code.
Related Functions
Examples
/* For the trend at AN20, get and display the number of samples */
INT nSamples;
nSamples=TrnSamplesConfigured(20);
DspStr(31,"",IntToStr(nSamples));

TrnScroll
Description Scrolls the trend pen by a specified percentage (of span), or number of samples.
Syntax TrnScroll(AN, Pen, nScroll, nMode)

AN....................The AN where the trend is located. Set to -1 for all trends on the current page.

Pen...................The trend pen number. Set to -1 for all pens.

nScroll .............The amount by which the trend will be scrolled. Use nMode to specify whether
the trend will be scrolled by percentage or by number of samples.

Because the resolution of Client requests is 1 second, requests of millisecond

accuracy are rounded to 1 second. For example, if requested to scroll 2 samples
of 400 milliseconds (a total of 0.8 seconds), the trend will actually scroll 1
second.

nMode..............The type of scrolling to be performed.

1 ..... The trend will be scrolled by a percentage of span.

2 ..... The trend will be scrolled by a number of samples. This mode is not
available if the user puts the trend into the 'trend span' mode by setting the
span. In this case no scrolling would take place; the user must use nMode
1.
630 TrnScroll

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnSetTime
Examples
! Scroll all pens (of the trend at an20) 100% forwards.
TrnScroll(20,-1,100); or TrnScroll(20,-1,100,1);

! Scrolls all pens (of all trends on the current trend page) 300%
backwards.
TrnScroll(-1, -1, -300); or TrnScroll(20,-1.-300,1);

!Scrolls all pens (of all trends on the current trend page) 3 samples
forwards.
TrnScroll(20,-1,3,2);

!Scrolls all pens (of all trends on the current trend page) 1 sample
backwards.
TrnScroll(20,-1,-1,2);

TrnSelect
Description Sets up a page for a trend. This function allows you to set up a trend before the trend page is
displayed. You can therefore use a single trend page to display any trend in the project by
selecting the trend first, and then displaying the trend page. The PageTrend() function uses this
function to display the standard trend pages.
Call this function and a set of TrnSetPen() functions before you display a trend page. When the
trend page is displayed, all pens set by the TrnSetPen() functions are displayed. You can use the
TrnSelect() function to configure different set of pens to be displayed on one generic trend page.
The pen settings in the Page Trend database are overridden.
NOTE: Trend functions used after the TrnSelect() function must use the special value -2 as their
AN. (See the example below).
Syntax TrnSelect(Window, Page, nAN)

Window ...........The window number (returned from the WinNumber function).

-3.... for the current window.

-2.... for the next window displayed.

Page ................The name of the page that displays the trend.

nAN .................The AN where the trend displays, or -3 for the first trend on the page.

Return Value 0 (zero) if successful, otherwise an error is returned.

 TrnSelect 631

Related Functions TrnSetPen, PageTrend, WinNumber

Examples
TrnSelect(WinNumber(), "TrendPage", 40);
TrnSetPen(-2,1,"PV1");
TrnSetPen(-2,2,"PV2");
TrnSetPen(-2,3,"PV3");
TrnSetPen(-2,4,"PV4");
PageDisplay("TrendPage");

TrnSetCursor
Description Moves the trend cursor by a specified number of samples. If the trend cursor is disabled, this
function enables it. If the cursor is enabled and the number of samples is 0 (zero), the cursor is
disabled. If the cursor is moved off the current trend frame, the trend scrolls.
Syntax TrnSetCursor(AN, Samples)

AN....................The AN where the trend is located. Set to -1 for all trends on the current page.

Samples............The number of samples to move the cursor.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetCursorTime, TrnGetCursorValue, TrnGetCursorValueStr, TrnSetCursorPos
Examples
! For the trend at AN20
TrnSetCursor(20,1);
! Moves the trend cursor forwards 1 sample.
TrnSetCursor(-1,-40);
! Moves the trend cursor (of all trends on the current trend page)
backwards 40 samples.

TrnSetCursorPos
Description Moves the trend cursor to a specified x-axis point, offset from the trend cursor origin. If the
trend cursor is disabled, this function enables it. If the position is outside of the trend frame, it
sets the trend cursor to half of the frame.
Syntax TrnSetCursorPos(AN, Position)

AN....................The AN where the trend is located. Set to -1 for all trends on the current page.
632 TrnSetCursorPos

Position ...........The x-axis point at which to position the trend cursor, offset from the trend
cursor origin.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetCursorPos, TrnSetCursor
Examples
! For the trend at AN20, if the trend frame is 400 points
TrnSetCursorPos(20,0);
! Moves the trend cursor to its origin.
TrnSetCursorPos(20,200);
! Moves the trend cursor to half of its frame size (200 points).

TrnSetDisplayMode
Description Specifies how raw trend samples are displayed on the screen.
Syntax TrnSetDisplayMode(AN, PenNumber, DisplayMode)

AN ...................The animation number of the chosen trend.

PenNumber......The pen number of the chosen trend. Specify:

0 ..... The current pen

1-8.. Pens 1 through 8
-1.... All pens

DisplayMode ...
BITS
Used for
0-1 Determines how invalid or gated trend values are processed
0 Invalid/Gated values are 0 (zero).
1 Invalid values are 0xFFFFBBBB; gated values are 0xFFFFAAAA.
2 Reverse the order of data in the table. Invalid/Gated values are 0 (zero).
3 Reverse the order of data in the table. Invalid values are 0xFFFFAAAA; gated
values are 0xFFFFBBBB.
NB These bits are not relevant to TrnSetDisplayMode().
2-6 The method of displaying the data when sample period is less than display period
(Condense modes).
 TrnSetDisplayMode 633

0 Mean 3 – 31 Reserved
1 Minimum
2 Maximum
7-11 The method of displaying the data when sample period is not less than display period
(Stretch methods) AND subgroups are not being used.
0 Step 2. Actual Raw Samples
1 Ratio 3 – 31 Reserved
12-19 The number of samples that can be missing before a gap is displayed
20-31 Reserved

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetDisplayMode
Examples

TrnSetEvent
Description Sets the start event of a trend pen. This function only operates on an event-based trend.
Syntax TrnSetEvent(AN, Pen, Event)

AN....................The AN where the trend is located.

Pen...................The trend pen number:

0 .... The pen currently in focus

1...8 Pen1. . .Pen8

Event................The number of the start event.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetEvent, TrnGetBufEvent, TrnGetCursorEvent
Examples
! Sets pen1 to event number 123456
TrnSetEvent(20,1,123456);
! Scrolls pen1 back by 100 events
TrnSetEvent(20,1,TrnGetBufEvent(20,1,0)-100);
634 TrnSetPen

TrnSetPen
Description Sets the trend tag of a trend pen. The trend pen changes to the specified tag and the trend is
refreshed. The trend pen must be in the operator's area to be displayed. If outside of the
operator's area, data is not displayed. You cannot mix periodic trends and event trends in the
same trend window.
Syntax TrnSetPen(AN, Pen, Tag)

AN ...................The AN where the trend is located.

-1.... All trends on the current trend page.

-2.... The function being called is using the special AN setup by the TrnSelect()
function.

Pen ..................The pen for which the trend tag will be changed.

-2.... The first available pen (This value is automatically changed to 0 for SPC
trends because they have only one pen per trend.)
-1.... All pens on the trend. (DO NOT USE for SPC trends.)
0 ..... The pen currently in focus.
1...8 Pen1....Pen8

Tag ..................The trend tag. If Tag = ! the pen is deleted.

Return Value 0 (zero) if successful, otherwise an error is returned. Note that if a mixture of periodic and event
trends is detected, the return value is 0 (zero), but the hardware alarm #329 is set.
Related Functions TrnGetPen, TrnSelect

! For the trend at AN20

TrnSetPen(20,1,"PV1");
! Sets the trend tag of Pen1 to "PV1".

TrnSetPenFocus
Description Sets the focus to a specified pen. After the focus is set, the focus pen is used with other trend
functions.
Syntax TrnSetPenFocus(AN, Pen)

AN ...................The AN where the trend is located.

Pen ..................The trend pen:

 TrnSetPenFocus 635

-4 ... Make the next pen the focus pen; do not skip blank pens.
-3 ... Make the previous pen the focus pen; do not skip blank pens.
-2 ... Make the next pen the focus pen; skip blank pens.
-1 ... Make the previous pen the focus pen; skip blank pens.
0 .... Do not change the focus pen.
1...8 Change Pen1. . .8 to be the focus pen.

Return Value The old pen focus number, or -1 if an error occurs. You can call the IsError()function to get the
actual error code.
Related Functions TrnGetPenFocus
Examples

System Keyboard
Key Sequence NextPen

Command TrnSetPenFocus(20, -2)

Comment For the trend at AN20, make the next pen

the focus pen

TrnSetPeriod
Description Sets the display period (time base) of a trend. When the period is changed, Citect reads the
historical data to reconstruct the trend data, and refreshes the trend. All pens have the same
display period.
This function clears the span set by the TrnSetSpan() function.
Syntax TrnSetPeriod(AN, Period)

AN....................The AN where the trend is located. Set to -1 for all trends on the current page.

Period ..............The new sampling period (in seconds) of the trend. To set the display period to
the sampling period, set this argument to 0 (zero),

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetPeriod, TrnEcho, TrendSetTimeBase, TrnSetSpan()
636 TrnSetPeriod

Examples

System Keyboard
Key Sequence ## Enter

Command TrnSetPeriod(20, Arg1)

Comment Set a new sampling period for the trend at

AN20

TrnSetScale
Description Sets a new scale for a trend pen. In the automatic scaling mode, the zero and full scales are
automatically generated.
Syntax TrnSetScale(AN, Pen, Percent, Scale)

AN ...................The AN where the trend is located. Set to -1 for all trends on the current page.

Pen ..................The trend pen number:

-1 ... All pens

0 .... The pen currently in focus
1...8 Pen1...Pen8

Percent ............The scale mode:

-2 ... Set both zero and full scales to the default scales.
-1 ... Place the trend into automatic scale mode.
0 .... Set the zero scale.
100 ........... Set the full scale.

Scale................The new value of the scale. Scale is ignored if Percent is -2.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetScale, TrnEcho, TrendSetScale
Examples
! For the trend at AN20
TrnSetScale(20,-1,100,5000.0);
! Sets the full scale of all pens to 5000.0
 TrnSetSpan 637

TrnSetSpan
Description Sets the span time of a trend. The span time is the total time displayed in the trend window.
You can set the period to contain fractions of a second. For example, if you set a trend with 240
samples to a span of 10 minutes, then each sample would be 2.5 seconds. Choose a span long
enough to ensure a sufficient sample rate to capture reliable real time data.
Syntax TrnSetSpan(AN, Span)

AN....................The AN where the trend is located.

Span.................The span time (in seconds).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnSetPeriod, TrnGetSpan, TrendSetSpan
Examples
// Set a span of 2 hours.
TrnSetSpan(40,StrToTime("2:00:00"));

// Then use TrnGetSpan function to display the span

Time = TrnGetSpan(40);
DspText(31,0,TimeToStr(Time,5));

TrnSetTable
Description Writes trend tag data from a table to the trend logging system (starting at the top of the table, and
continuing to the bottom). Each value is written with a time and date, as specified by Period. If
Period differs from the trend sampling period (defined in the Trend Tags database), the trend's
sample values will be calculated (averaged or interpolated) from the tabulated trend data.
The user must have the correct privilege (as specified in the database), otherwise the data is not
written.
This function is a blocking function. It will block the calling Cicode task until the operation is
complete.
Syntax TrnSetTable(Tag, Time, Period, Length, Table, Milliseconds)

Tag...................The trend tag.

Time.................The time and date (long integer) to be associated with the first value in the table
when it is set. Once you have entered the end time and date (Time), set period
(Period), and number of trend tag values to be set (Length), the start time and
date will be calculated automatically. For example, if Time =
StrToDate("18/12/96") + StrToTime("09:00"), Period = 30, and Length = 60,
638 TrnSetTable

the start time would be 08:30. In other words, the first value from the table
would be set with time 9am, and the last would be set with time 8.30am (on
December 18, 1996).

Period..............This will be the interval (in seconds) between trend values when they are set (i.e.
it will be the perceived sampling period for the trend). This period can differ
from the actual trend period. Set to 0 (zero) to default to the actual trend period.

Length .............The number of trend values in the trend table.

Table ...............The table of floating-point values in which the trend data is stored. You can
enter the name of an array here (see the example).

Milliseconds ....This argument allows you to set the time of the first sample in the table with
millisecond precision. After defining the time and date in seconds with the Time
argument, you can then use this argument to define the milliseconds component
of the time.

For example, if you wanted to set data from the 18/12/96, at 9am, 13 seconds,
and 250 milliseconds you could set the Time and Milliseconds arguments as
follows:
Time = StrToDate("18/12/96") + StrToTime("09:00:13")
Milliseconds = 250
If you don't enter a Milliseconds value, it defaults to 0 (zero). There is no range
constraint, but as there are only 1000 milliseconds in a second, you should keep
your entry between 0 (zero) and 999.

Return Value The actual number of samples read. The return value is 0 if an error occurs. You can call the
IsError()function to get the actual error code.
Related Functions TrnGetTable
Examples
REAL TrendTable1[100];
/* Defines an array of a maximum of 100 entries. Assume that TrendTable1
has been storing data from a source. */

TrnSetTable("OP1",StrToDate("18/12/91")
+StrToTime("09:00"),2,10,TrendTable1[0]);
/* A set of 10 trend data values are set for the OP1 trend tag. */
 TrnSetTime 639

TrnSetTime
Description Sets the end time and date of a trend pen. Samples taken after this time and date will not be
displayed.
Syntax TrnSetTime(AN, Pen, Time)

AN....................The AN where the trend is located, or:

-1 ... All trends on the current page

0 .... The trend where the cursor is positioned

Pen...................The trend pen number:

-1 ... All pens

0 .... The pen currently in focus
1...8 Pen1. . .Pen8

Time.................The end time and date of the trend. Samples taken after this time and date will
not be displayed. Set to 0 (zero) to set the trend to the current time (real-time
mode).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions TrnGetTime, TrendSetTime
Examples
TrnSetTime(20,1,TimeCurrent()-60*30);
/* Sets Pen1 to 30 minutes before the current time (30 minutes ago). */
TrnSetTime(20,1,0);
/* Sets the trend to real-time mode. */

UserCreate
Description Creates a record for a new user. A new user of the specified type is created. The name of the
user must be unique.
Syntax UserCreate(sName, sFullName, sPassword, sType)

sName ..............The name of the user.

sFullName .......The full name of the user.

sPassword........The password of the user.

640 UserCreate

sType ...............The generic type of user. The type must be defined in the Users database (with
the Users form).

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions UserDelete, UserEditForm, UserPassword, UserPasswordForm, UserCreateForm
Examples
/* Create a new user */
UserCreate("Fred", "Fred Jones", "secret", "Operator");

UserCreateForm
Description Displays a form to create a record for a new user. A new user of the specified type is created.
The name of the user must be unique.
Syntax UserCreateForm()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions UserDelete, UserEditForm, UserPassword, UserPasswordForm, UserCreate
Examples
UserCreateForm()

UserDelete
Description Deletes the record for a user. Changes are written to both the Users database and the runtime
database in memory.
Syntax UserDelete(sName)

sName.............. The name of the user.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions UserCreate, UserEditForm
Examples
/* Delete Fred from the database */
UserDelete("Fred");
 UserEditForm 641

UserEditForm
Description Displays a form to allow the user to create or delete any user record in the database. This
function should have restricted access. Changes are written to both the Users database and the
runtime database in memory.
Syntax UserEditForm()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions UserCreate, UserDelete
Examples
/* Display a form for the user to create or delete user records. */
UserEditForm();

UserInfo
Description Gets information about the operator who is currently logged-in to the system.
Syntax UserInfo(Type)

Type .................The type of user information:

0 ..... Flag to indicate if anyone is logged in or not

1 ..... The login name of the user
2 ..... The full name of the user
3 ..... The time the user logged in
4 ..... The time the user entered the last command
5 ..... The number of commands entered by the user

Return Value The information (as a string). If an error occurs, an empty string is returned.
Related Functions Login
Examples
/* Check if a user has logged on. If so, get the user's full name and
the number of commands they have performed. */
String sName;
String sCount;

IF UserInfo(0) = "1" THEN

sName = UserInfo(2);
sCount = UserInfo(5);
642 UserInfo

END

UserPassword
Description Changes the password for the user. Changes are written to both the Users database and the
runtime database in memory.
Syntax UserPassword(sName, sPassword)

sName.............. The name of the user.

sPassword .......The password of the user.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions UserPasswordForm, UserCreate, UserEditForm
Examples
/* Change Fred's password */
UserPassword("Fred", "secret");

UserPasswordForm
Description Display a form to allow users to change their own passwords. Changes are written to both the
Users database and the runtime database in memory.
Syntax UserPasswordForm()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions UserPassword, UserCreate, UserEditForm
Examples
/* Allow users to change their own passwords */
UserPasswordForm();

Version
Description Gets the version number of the Citect software in use.
Syntax Version(Type)

Type.................The type of version:

 Version 643

0 .... Major version number

1 .... Minor version number
2 .... Revision number
3 .... Version text

Return Value The version number as a string.

Examples
! If the Citect version number is 1.2:
Version(0);
! Returns 1.
Version(1);
! Returns 2.
Version(3);
! Returns "1.2".

WhoAmI
Description Displays the user name and full name of the user currently logged-in to the system. The names
are displayed at the prompt AN.
Syntax WhoAmI()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions Name, FullName, UserInfo
Examples
/* Display the user's full name and user name at the prompt AN. */
WhoAmI();

WinCopy
Description Copies the graphics image of the active window into the Windows clipboard. You can paste this
clipboard image into other applications.
Syntax WinCopy()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinPrint
Examples
644 WinCopy

WinCopy();
! Copies the active window into the Windows clipboard.

WinFile
Description Writes the graphics image of the active window to a file. The file is saved in the Citect
compressed .BMP format.

NOTE: This function will only work under 8 bit colour (256 colours).

Syntax WinFile(Filename)

Filename .........The name of the file.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinPrint
Examples
WinFile("DUMP");
/* Writes the active window to a file named DUMP in the current
directory. */

WinFree
Description Removes the active display window. Note that the last window (and any child windows owned
by the last window) cannot be removed. You cannot call this function as an exit command (see
Page Properties) or from a Cicode Object.
Syntax WinFree()

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinNew, WinNewAt
Examples
WinFree();
! Removes the active display window.
 WinGetFocus 645

WinGetFocus
Description Gets the number of the Citect window that has the keyboard focus.
Syntax WinGetFocus()

Return Value The window number of the Citect window that has the keyboard focus. Note that this is not the
same as the window handle, returned from the WndFind() function.
Related Functions WndFind
Examples
nCitectWin=WinGetFocus();
! Gets the number of the Citect window that has the keyboard focus

WinGetWndHnd
Description Gets the window handle for the current window. The window handle may be used by 'C'
programs and Citect Wnd... functions. You may pass the windows handle to a 'C' program by
using the DLL functions.
Syntax WinGetWndHnd()

Return Value The window handle if successful, otherwise 0 (zero) is returned. Note that this is not the same as
a Citect window number returned from the WinNumber() function.
Related Functions DLLCall, WinNew, WndFind, WndShow
Examples
INT hWnd;

hWnd = WinGetWndHnd();
WinShow(hWnd,6); //iconise the window

WinGoto
Description Changes the active window. The specified window is placed in front of all other windows and
all keyboard commands will apply to this window. You cannot call this function as an exit
command (see Page Properties) or from a Cicode Object.
Syntax WinGoto(Window)

Window............The window number (returned from the WinNumber() function). Note that this
is not the same as the window handle, returned from the WndFind() function.
646 WinGoto

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinNew
Examples
! If two windows are displayed;
WinGoto(1);
! Changes the active window to Window 1.
WinGoto(0);
! Changes the active window to Window 0.

WinMode
Description Sets the display mode of the active Citect window.
Syntax WinMode(Mode)

Mode ...............The mode:

0 .... Hide the window.

2 .... Activate the window in an iconised state.
3 .... Activate the window in a maximised state.
4 .... Display the window in its previous state without activating it.
5 .... Activate the window in its current state.
6 .... Iconise the window.
7 .... Display the window in an iconised state without activating it.
8 .... Display the window in its current state without activating it.
9 .... Activate the window in its previous state.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinNew
Examples
! Iconise the active Citect window.
WinMode(7);
 WinMove 647

WinMove
Description Moves the active window to a new location and sizes the window in a single operation. This is
the same as calling the WinPos() and the WinSize() functions. You use PageInfo() to get the
current window position
Syntax WinMove(X, Y, Width, Height)

X ......................The new x and y pixel coordinates of the top left corner of the active window.

Y.......................The new x and y pixel coordinates of the top left corner of the active window.

Width ...............The width of the window, in pixels.

Height ..............The height of the window, in pixels.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinSize, WinPos PageInfo
Examples
WinMove(100,50,500,300);
/* Moves the top-left corner of the active window to the pixel
coordinate 100,50 and
size the window to 500 x 300 pixels. */

WinNew
Description Opens a display window. The specified page displays in the new window. The window can
later be destroyed with the WinFree() function.
Syntax WinNew(Page)

Page.................The Page Name or Page Number of the page to display in the window.

Return Value The window number of the window, or -1 if the window cannot be opened. Note that this is not
the same as the window handle returned from the WndFind() function.
Related Functions WinFree
Examples
! If the display window being opened is window number 2:
Window=WinNew("Alarm");
! Displays the Alarm page and sets Window to 2.
648 WinNewAt

WinNewAt
Description Opens a display window at a specified location. The specified page displays in the new window.
The window can later be destroyed with the WinFree() function.
Syntax WinNewAt(Page, X, Y, Mode)

Page ................The Page Name or Page Number of the page to display in the window.

X ......................The x pixel coordinate of the top left corner of the window.

Y ......................The y pixel coordinate of the top left corner of the window.

Mode ...............The mode of the window:

0 ..... Normal page.

1 ..... Page child window. The window is closed when a new page is displayed,
e.g. when the PageDisplay() or PageGoto() function is called. The parent is
the current active window.
2 ..... Window child window. The window is closed automatically when the
parent window is freed with the WinFree() function. The parent is the
current active window.
4 ..... No re-size. The window is displayed with thin borders and no
maximise/minimise icons. The window cannot be re-sized.
8 ..... No icons. The window is displayed with thin borders and no
maximise/minimise or system menu icons. The window cannot be re-sized.
16 .. No caption. The window is displayed with thin borders, no caption, and no
maximise/minimise or system menu icons. The window cannot be re-sized.
32 .. Echo enabled. When enabled, all keyboard echo, prompts, and error
messages are displayed on the parent window. This mode should only be
used with child windows (e.g. Mode 1 and 2).
64 .. Always on top.
128 ........... Open a unique window. This mode prevents this window from
being opened more then once.
256 .............Display the entire window. This mode ensures that no parts of the
window will appear off the screen
512 .............Open a unique Super Genie. This mode prevents a Super Genie
from being opened more than once (at the same time). However, the
same Super Genie with different associations can be opened.
 WinNewAt 649

1024........... Disables dynamic resizing of the new window, overriding the setting
of the [Page]DynamicSizing parameter.
You can select multiple modes by adding modes together (for example, set Mode
to 9 to open a page child window without maximise, minimise, or system menu
icons).

Return Value The window number of the window, or -1 if the window cannot be opened. Note that this is not
the same as the window handle returned from the WndFind() function.
Related Functions WinFree, WinNew, WinNewAt
Examples

Buttons
Text Mimic Page

Command WinNewAt("Mimic", 100, 20, 0)

Comment Display the mimic page in a new window

at coordinate 100, 20.

Buttons
Text Pop Page

Command WinNewAt("Popup", 100, 200, 2)

Comment Display the popup page in a child

window at coordinate 100, 200

Buttons
Text Pop Page

Command WinNewAt("Popup", 100, 200, 4)

Comment Display the popup page in a new window

with no maximise and minimise icons
650 WinNewAt

System Keyboard
Key Sequence Pop ######## Enter

Command WinNewAt(Arg1, 100, 200, 2)

Comment Display a specified popup page in a child

window at coordinate 100, 200

System Keyboard
Key Sequence Pop ######## Enter

Command WinNewAt(Arg1, 100, 200, 4)

Comment Display a specified popup page in a new

window with no maximise and minimise
icons

WinNext
Description Makes the next window (in order of creation) active.
Syntax WinNext()

Return Value The window number of the window, or -1 if there is no next window. Note that this is not the
same as the window handle returned from the WndFind() function.
Related Functions WinNew, WinPrev
Examples
! If the display window being made active is window number 2:
Window=WinNext();
! Makes the next window active and sets Window to 2.

WinNumber
Description Gets the window number of the active Citect window. This number can be used with other
functions to control the window.
Syntax WinNumber()
 WinNumber 651

Return Value The window number of the window. Note that this is not the same as the window handle
returned from the WndFind() function.
Related Functions WinNew, WinGoto
Examples
! Create a new window, but keep the active window the same:
Window=WinNumber();
WinNew("Alarm");
WinGoto(Window);

WinPos
Description Moves the active window to a new location. You use PageInfo() to get the current window
position
Syntax WinPos(X, Y)

X ......................The new x and y pixel coordinates of the top left corner of the active window.

Y.......................The new x and y pixel coordinates of the top left corner of the active window.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinSize, WinMove PageInfo
Examples
WinPos(100,50);
/* Moves the top-left corner of the active window to the pixel
coordinate 100,50. */

WinPrev
Description Makes the previous window (in order of creation) active.
Syntax WinPrev()

Return Value The window number of the window, or -1 if there is no next window. Note that this is not the
same as the window handle returned from the WndFind() function.
Related Functions WinNext
Examples
! If the display window being made active is window number 2:
Window=WinPrev();
652 WinPrev

! Makes the previous window active and sets Window to 2.

WinPrint
Description Sends the graphics image of the active window to a printer.

NOTE: This function will only work under 8 bit colour (256 colours).

Syntax WinPrint(sPort, xScale, yScale, sPalette)

sPort ......... The name of the printer port to which the window will be printed. This
name must be enclosed within quotation marks "". For example "LPT1:",
to print to the local printer, or "\\Pserver\canon1" using UNC to print to
a network printer.

xScale .............. The x scaling factor for the print. Set to 0 (zero) to automatically scale the print
to fit the page.

yScale .............. The y scaling factor for the print. Set to 0 (zero) to automatically scale the print
to fit the page.

sPalette............ The name of an alternative palette file. This file could be used to map alternative
colours to the printer or reverse black and white.

Leave sPalette blank to use the default palette file PRINTER.PAL. Enter a
blank string "" to use the display palette CITECT.PAL.
The format of the palette file is:
<Col No> <Red> <Green> <Blue> <Red> <Green> <Blue> <Colour Name>
For example:
000 255 255 255 255 255 255 "White"
001 000 000 128 000 000 128 "Blue"
002 000 128 000 000 128 000 "Green"
003 000 128 128 000 128 128 "Cyan"
004 128 000 000 128 000 000 "Red"
005 128 000 128 128 000 128 "Magenta"
006 128 128 000 128 128 000 "Brown"
007 192 192 192 192 192 192 "Grey"
008 128 128 128 128 128 128 "Dk Grey"
 WinPrint 653

009 000 000 255 000 000 255 "Lt Blue"

010 000 255 000 000 255 000 "Lt Green"
011 000 255 255 000 255 255 "Lt Cyan"
012 255 000 000 255 000 000 "Lt Red"
013 255 000 255 255 000 255 "Lt Magenta"
014 255 255 000 255 255 000 "Yellow"
015 000 000 000 000 000 000 "Black"
016 000 000 000 000 000 000 "Opaque Black"
....... .
....... .
....... .
125 143 000 143 143 000 143 ""
126 143 143 000 143 143 000 ""
127 200 200 200 200 200 200 ""
NOTE:....... The second set of RGB columns is identical to the first for a printer
palette. In a display palette these values represent the on and off
colours for flashing colours.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinPrintFile
Examples
WinPrint("LPT3:",0,0,"");
! Prints the active window on printer "LPT3". The print will be scaled
to fit the largest possible page area and will retain the orientation of
the printer, aspect ratio and colours that are displayed on the screen.

WinPrintFile
Description Prints a file to the system printer. The file must be saved with the WinFile() function.
Syntax WinPrintFile(sFile, sPort, xScale, yScale, sPalette)

sFile.................The file name.

sPort ..........The name of the printer port to which the window will be printed. This
name must be enclosed within quotation marks "". For example "LPT1:",
654 WinPrintFile

to print to the local printer, or "\\Pserver\canon1" using UNC to print to

a network printer.

xScale .............. The x scaling factor for the print. Set to 0 (zero) to automatically scale the print
to fit the page.

yScale .............. The y scaling factor for the print. Set to 0 (zero) to automatically scale the print
to fit the page.

sPalette............ The name of an alternative palette file. This file could be used to map alternative
colours to the printer or reverse black and white.

Leave sPalette blank to use the default palette file PRINTER.PAL. Enter a
blank string "" to use the display palette CITECT.PAL.
The format of the palette file is:
<Col No> <Red> <Green> <Blue> <Red> <Green> <Blue> <Colour Name>
For example:
000 255 255 255 255 255 255 "White"
001 000 000 128 000 000 128 "Blue"
002 000 128 000 000 128 000 "Green"
003 000 128 128 000 128 128 "Cyan"
004 128 000 000 128 000 000 "Red"
005 128 000 128 128 000 128 "Magenta"
006 128 128 000 128 128 000 "Brown"
007 192 192 192 192 192 192 "Grey"
008 128 128 128 128 128 128 "Dk Grey"
009 000 000 255 000 000 255 "Lt Blue"
010 000 255 000 000 255 000 "Lt Green"
011 000 255 255 000 255 255 "Lt Cyan"
012 255 000 000 255 000 000 "Lt Red"
013 255 000 255 255 000 255 "Lt Magenta"
014 255 255 000 255 255 000 "Yellow"
015 000 000 000 000 000 000 "Black"
016 000 000 000 000 000 000 "Opaque Black"
....... .
 WinPrintFile 655

....... .
....... .
125 143 000 143 143 000 143 ""
126 143 143 000 143 143 000 ""
127 200 200 200 200 200 200 ""
NOTE:....... The second set of RGB columns is identical to the first for a printer
palette. In a display palette these values represent the on and off
colours for flashing colours.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinPrint
Examples
! save image to disk then print.
WinFile("temp");
! print to LPT1:
WinPrintFile("temp", "LPT1:",0,0,"");

WinSelect
Description Selects a window to make active. This function only affects the output of Cicode functions. It
does not change the screen focus of the windows, or move a background window to the
foreground.
Always re-select the original window if it is called from a Page database (Page Numbers, Page
Symbols, etc.), because other Cicode tasks will assume it is the correct window. This function
only changes the active window for the Cicode task that called it.
Syntax WinSelect(Window)

Window............The window number to select. Note that this is not the same as the window
handle returned from the WndFind() function.

Return Value The old window number.

Related Functions WinGoto, WinNumber
Examples
OldWindow=WinSelect(1);
! Selects window number 1.
Prompt("Message to Window 1");
! Sends message to window number 1.
WinSelect(2);
656 WinSelect

! Selects window number 2.

Prompt("Message to Window 2");
! Sends message to window number 2.
WinSelect(OldWindow);
! Selects original window.

WinSize
Description Sizes the active window. The origin of the window does not move.
Syntax WinSize(Width, Height)

Width ...............The new width and height of the window, in pixels.

Height..............The new width and height of the window, in pixels.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinMove, WinPos
Examples
WinSize(200,100);
! Sizes the active window to 200 pixels wide x 100 pixels high.

WinTitle
Description Sets the title of the active window.
If a window title has been set with the [Page] WinTitle parameter, Citect uses this title when it
refreshes the page (overriding the window title set with the WinTitle() function). To prevent
Citect from overriding the title, set the parameter [Page] WinTitle to *.
Syntax WinTitle(sTitle)

sTitle................ The new title for the window.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WinNew
Examples
WinTitle(Time()+" "+Date());
! Places the current time and date into the window title.
 WndFind 657

WndFind
Description Gets the Windows handle of any window of any application, so that the window can be
manipulated. The window handle is not the same as the Citect window number and cannot be
used with functions that expect the Citect window number (the Win... functions).
The window title (caption) must be an exact match of the window name (including any blank
spaces) for this function to find the window. You should therefore check that the other
application does not change the title of the window during execution.
Note that if the title banner of a Citect window is set with the Citect parameter [Page] WinTitle,
you should not specify justification (for example, use {TITLE,32,N}). If justification is not
disabled (i.e. the N is omitted), you must pass the full title of the window (including leading and
trailing blanks) to this function.
Syntax WndFind(sTitle)

sTitle ................The title (caption) of the window.

Return Value The window handle. Note that this is not the same as a Citect window number returned from the
WinNumber() function.
Related Functions WinNew
Examples
hWndExcel=WndFind("Microsoft Excel");
! Gets the Windows number of the window
titled "Microsoft Excel".

WndGetFileProfile
Description Gets a profile string from any .INI file.
Syntax WndGetFileProfile(sGroup, sName, sDefault, sFile)

sGroup .............The name of the [group].

sName ..............The name of the variable.

sDefault ...........The default value.

sFile.................The .INI file name.

Return Value The profile string from sFile.

Related Functions WndPutFileProfile, WndGetProfile, WndPutProfile
658 WndGetFileProfile

Examples
! get this user startup page from
! USER.INI File
sStartup = WndGetFileProfile(Name(),"Startup","menu","USER.INI");
PageDisplay(sStartup);

WndGetProfile
Description Gets the value of a WIN.INI parameter. If the parameter has no value or does not exist, the
default value is returned.
Syntax WndGetProfile(Group, Parameter, Default)

Group .............. The WIN.INI group name.

Parameter........The parameter name.

Default.............The default value of the parameter.

Return Value The value of the WIN.INI parameter (as a string).

Related Functions WndPutProfile
Examples
KeyboardSpeed=WndGetProfile("Windows","KeyboardSpeed","20");
/* Sets KeyboardSpeed to "20" if the [Windows] KeyboardSpeed parameter
has no value or does not exist. */

WndHelp
Description Invokes the Windows Help application (WinHlp32.EXE) to display a specific topic from a
specific help file.
Syntax WndHelp(sHelpFile, Command, Data)

sHelpFile......... The help file to display.

Command ........The type of help:

1 ..... Displays the help topic identified by the context string/number in the Data
field. The context string/number must be defined in the [MAP] section of
the help's .HPJ file.
2 ..... Closes the Help application. Enter an empty string for the Data argument.
 WndHelp 659

3 ..... Displays the help contents topic defined by the CONTENTS option in the
[OPTIONS] section of the .HPJ file.
4 ..... Displays the contents topic of the designated How to Use Help file. The
context string/number (specified in the Data field) must be defined in the
[MAP] section of the .HPJ file.
5 ..... Changes the current help contents topic to match the context string/number
specified in the Data field. This topic is used instead of the one defined by
the CONTENTS option in the [OPTIONS] section of the .HPJ file. NOTE:
This will affect Command 3 (see above). The context string/number must
be defined in the [MAP] section of the help's .HPJ file, and the help file
must already be open. The change will last only until the help file is closed.
8 ..... Displays, in a pop-up window, the help topic identified by the context
string/number in the Data field. The context string/number must be defined
in the [MAP] section of the .HPJ file.
9 ..... Ensures that the correct help file is displayed. If the correct help file is
currently displayed, this command merely makes the help the active
window. If the incorrect help file is displayed, WinHelp opens the correct
file, and displays the help contents topic defined by the CONTENTS option
in the [OPTIONS] section of the .HPJ file. NOTE: This command will not
distinguish between two files of the same name, regardless of their paths.
11.... Displays the Citect Help Topics with either the Contents, the Index, or the
Find tab selected, depending on which one was last used. Enter an empty
string for the Data argument.
257............. Searches the help index for your keyword (as specified in the Data
field) and displays the first topic in the index with an identical
match. If there is no match, displays the index with your keyword
already entered. To display the index without passing a keyword,
enter an empty string for the Data argument.
258............. Executes the Help macro string specified in the Data field. Help
must be running and the help file must be open, or the message is
ignored.
260............. Displays, in a pop-up window, the help topic identified by the
context string/number in the Data field.
261............. Searches the help index for your keyword (as specified in the Data
field) and displays the first topic in the index with an identical
match. If there is no match, displays the index with your keyword
already entered. To display the index without passing a keyword,
enter an empty string for the Data argument.

Data.................The context string/number or keyword of the help topic that is requested.

660 WndHelp

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WndViewer
Examples
WndHelp("MyHelp.HLP", 3, 1);
! Displays the "MyHelp" Contents page.
WndHelp("C:\Help\Process.HLP", 8, 239);
! Displays topic labelled "239" in the "Process" help file.

WndInfo
Description Gets information on the window system (such as the widths and heights of the various elements
displayed by Windows). WndInfo() can also return flags that indicate whether the current
version of the Windows operating system is a debugging version, whether a mouse is present, or
whether the functions of the left and right mouse buttons have been exchanged.
Syntax WndInfo(Type)

Type.................The system measurement to be retrieved. All measurements are in pixels. The

system measurement must be one of the following values:

0 ..... Width of the screen.

1 ..... Height of the screen.
2 ..... Width of the arrow bitmap on a vertical scroll bar.
3 ..... Height of the arrow bitmap on a horizontal scroll bar.
4 ..... Height of the window title. This is the title height plus the height of the
window frame that cannot be sized (SM_CYBORDER).
5 ..... Width of the window frame that cannot be sized.
6 ..... Height of the window frame that cannot be sized.
7 ..... Width of the frame when the window has the WS_DLGFRAME style.
8 ..... Height of the frame when the window has the WS_DLGFRAME style.
9 ..... Height of the scroll box on vertical scroll bar.
10 ... Width of the scroll box (thumb) on horizontal scroll bar.
12 ... Height of the icon.
13 ... Width of the cursor.
14 ... Height of the cursor.
 WndInfo 661

15.... Height of a single-line menu bar. This is the menu height minus the height
of the window frame that cannot be sized (SM_CYBORDER).
16.... Width of the window client area for a full-screen window.
17.... Height of the window client area for a full-screen window (equivalent to
the height of the screen minus the height of the window title).
18.... Height of a Kanji window.
19.... Non-zero if the mouse hardware is installed.
20.... Height of arrow bitmap on a vertical scroll bar.
21.... Width of arrow bitmap on a horizontal scroll bar.
22.... Non-zero if the Windows version is a debugging version.
23.... Non-zero if the left and right mouse buttons are swapped.
24-27 Not Used
28.... Minimum width of the window.
29.... Minimum height of the window.
30.... Width of bitmaps contained in the title bar.
31.... Height of bitmaps contained in the title bar.
32.... Width of the window frame that can be sized.
33.... Height of the window frame that can be sized.
34.... Minimum tracking width of the window.
35.... Minimum tracking height of the window.

Return Value The system metric information.

Examples
width = WndInfo(0); ! get width of screen
height = WndInfo(1); ! get height of screen
WinPos(width/2, height/2); ! move window to centre of screen

WndPutFileProfile
Description Puts a profile string into any .INI file.
Syntax WndPutFileProfile(sGroup, sName, sData, sFile)

sGroup .............The name of the [group].

662 WndPutFileProfile

sName.............. The name of the variable.

sData ...............The variable data.

sFile................. The .INI file name.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WndGetFileProfile
Examples
WndPutFileProfile(Name(), "What", "100", "USER.INI");

WndPutProfile
Description Updates a parameter in WIN.INI. If the parameter does not exist, it is created.
Syntax WndPutProfile(Group, Parameter, Value)

Group .............. The WIN.INI group name.

Parameter........The parameter name.

Value ...............The value to put in the parameter.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WndGetProfile
Examples
WndPutProfile("Windows","KeyboardSpeed","20");
! Updates the [Windows] KeyboardSpeed
parameter in WIN.INI with "20".

WndShow
Description Sets the display mode of any window of any application.
Syntax WndShow(hWnd, nMode)

hWnd ...............The Windows handle of the window (returned from the WndFind() function).
Note that this is not the same as a Citect window number returned from the
WinNumber() function.
 WndShow 663

nMode..............The mode:

0 .... Hide the window.

2 .... Activate the window in an iconised state.
3 .... Activate the window in a maximised state.
4 .... Display the window in its previous state without activating it.
5 .... Activate the window in its current state.
6 .... Iconise the window.
7 .... Display the window in an iconised state without activating it.
8 .... Display the window in its current state without activating it.
9 .... Activate the window in its previous state.

Return Value 0 (zero) if successful, otherwise an error is returned.

Related Functions WndFind
Examples
WndShow(WndFind("Microsoft Excel"), 0);
! Hides the "Microsoft Excel" window.

WndViewer
Description Invokes the Microsoft Multimedia application.
Syntax WndViewer(sViewerFile, Command, Data)

sViewerFile......The Multimedia Viewer file to display.

Command ........The type of help:

1 ..... Displays a Viewer topic (specified in the Data field) in the main Viewer
window.
2 ..... Displays a Viewer topic (specified in the Data field) in a pop-up window.

Data.................The context string of the Multimedia Viewer topic.

Return Value 0 (zero) if successful, otherwise an error is returned.

Note that Citect cannot test if the topic has been found or displayed correctly. For example, if
you pass an invalid topic, the viewer will open with "Viewer topic does not exist" - but this
function will return 0.
664 WndViewer

Related Functions WndHelp

Examples
WndViewer("MyFile.MVB",1, "Contents");
! Displays the contents topic in the Multimedia file "MyFile.MVB".
WndViewer("HelpFile.MVB",2, "HelpTip");
! Displays the HelpTip topic in the Multimedia file "HelpFile.MVB" in a
popup.
WndViewer 665
 665

Part D
Cicode Errors
 Cicode Errors 667

Citect 'traps' system errors automatically. When a system error occurs, Citect generates a hardware
alarm, and the corresponding error message is placed in the alarm description. Each error has an
associated (unique) error number.
Range Source Cause
0-31 PLC or I/O Device The I/O Device is reporting an error, or Citect is
Generic errors experiencing the reported error trying communicate with
an I/O Device. Often caused by incorrect configuration or
faulty cabling.
256-511 General General errors are wide ranging, from animation to server
problems. However, there are two main causes of general
errors:
Device External devices such as printers, databases, and files can
cause many different hardware errors since they are
beyond the control of Citect. Often the device itself is
faulty or non-existent.
Cicode Cicode errors are generated when your project
configuration calls a Cicode function in an invalid way, or
when a Cicode function fails or does illegal operations.
1024-1279 NetBIOS These are very uncommon, but point to bad network
configuration.
You can use the IsError() function to get the number of the last error. Alternatively, you can trap and
process errors within your user functions. Use the ErrSet() function to enable or disable error
trapping.
668 Cicode Errors

Cicode and General Errors

256 General software error

An internal Citect software error is detected. Contact Citect Support and provide details on what
causes the error.

257 Value is out of range

A numeric value is out of range. An out-of-range value has been passed to a function, or an array
index is off the end of an array, or a value that is outside of the specified engineering scale has been
assigned to a I/O Device variable. You can disable range checking on PLC variables with the
CodeSetMode() function.

258 Buffer has been overrun

A buffer has been overrun. More data has been passed to a function than it can write to its temporary
buffers. Try again by calling the function twice, with half the data in each call.

259 Array has been overrun

An array passed to a function is too small for the data requested. Define a larger array or reduce the
maximum data size requested.

260 Path does not exist

The specified path to a device or file does not exist. During a function call (that tried to open a file), a
non-existent path was specified. Call the function again with the correct path.

261 File does not exist

The specified file or device does not exist. During a function call (that tried to open a file), the file
could not be found. Call the function again with the correct file name.

262 Cannot open file

The specified file cannot be opened. During a function call (that tried to open a file), the file could not
be opened. There may be a mode error (e.g. from trying to open a read-only file in write mode), or the
file may be open by others, or the operating system resources may be too low to open the file.
Check that the file does exist (use File Manager), and that you have the correct rights to open it.
(Check with your network supervisor that you have correct rights to open the file).

263 Cannot read file

The specified file cannot be read. Either an error occurred during a read operation, or the end of file
 Cicode Errors 669

was unexpectedly found, or a loss of the file server occurred, or the operating system is out of
resources.

264 Cannot write to file

The specified file cannot be written to. During a function call (that tried to write to a file), a write
error occurred. There could be a disk full error, or a loss of the file server may have occurred, or the
operating system is out of resources.

265 Invalid file type

An attempt was made to open a file of the wrong type, e.g. you tried to open an ASCII file as a dBASE
file.

266 Field not found in file

The specified field does not exist in the device or database. A function that is trying to access an
individual field in a database cannot find that field. Check that you have specified the correct field
name and database name.

267 File mode is invalid

An operation has been attempted on a file or device that is of the wrong mode, e.g. you tried to
perform a seek on a printer device. Do not use this operation on this type of device.

268 Key not found in file

The requested key was not found when a key search was performed on a database device, i.e. the
record specified on an indexed search cannot be found. Either the record does not exist or you have
specified the wrong key.

269 Bad handle specified

A bad handle has been passed to a function. You have called a function that requires a device handle,
font handle, window handle, etc., but you passed a number that does not associate with a read device,
font, or window (e.g. you called WinGoto(100) when no window with the handle "100" exists). Check
where the handle or number was retrieved from, and make sure it is the same handle. This error may
also occur if you have closed or destroyed the resource and you then try to access it.

271 No more free handles left

All the available file handles have been used, i.e. too many files or databases are open at the same
time. Open fewer files at one time or increase the number of file handles in the [CtEdit]DBFiles
parameter.
670 Cicode Errors

272 Out of memory

Citect is out of memory. Increase the amount of memory in the computer or use smaller databases.

273 Divide by zero

An attempt has been made to divide a number by zero.

274 Invalid argument passed

An invalid argument has been passed to a Cicode function. This is a general error message and is
generated when arguments passed to a function are out of range or are invalid. Check the value of
arguments being passed to the function. If arguments are input directly from the operator, you should
check that the correct arguments are being passed to the function.

275 Overflow
A calculation has resulted in a numeric value overflow. Check for operations that will generate very
large numbers.

276 No privilege for operation

A user has requested an operation for which he or she has no privilege.

277 Not in correct area

A user has requested data that does not belong to the current user area.

278 Report already busy

A request has been made to run a report that is already running. You can get the current state of a
report with the RepGetControl() function. You can ignore this error message (because the report is
already running).

279 Report is late for execution

The report cannot run at the rate requested in the configuration. An attempt could have been made to
run a report too frequently, and the required data cannot be read from the I/O Device(s) in time for the
next report.

280 Invalid report ID specified

The specified report name does not exist, or the user has no privilege to run the report, or the report is
not in the current user area. Check the name of the report and the current user's privilege and areas.

281 No server could be found

The specified Citect server cannot be found. Either the server is not running or there is some
 Cicode Errors 671

communication problem with the network. Check that the network is set up correctly, and the [Lan]
Disable parameter is set to 0 (zero), and you are using the same Server Name on both the client and
server.

282 Foreground Cicode cannot block

You cannot block the foreground Citect task. You may have called a blocking function from one of
the Page animation databases.

283 Trend has missed samples

The trend cannot run at the rate requested in the configuration. An attempt could have been made to
trend the data too frequently, and the required data cannot be read from the I/O Device(s) in time for
the next trend. Either increase the performance of the communication link to the PLCs or slow the rate
of trend data acquisition.

284 Device is disabled

An attempt was made to access a device that is disabled. You can disable any devices (printers and
other logging devices) with the DevDisable() function. When Citect (or your Cicode function) tries to
access a disabled device, this error message returns and all output is lost.

285 Foreground Cicode run is too long

The foreground Cicode task is taking too long to animate the display page. The Cicode is too complex
and is taking too long to execute. Simplify the Cicode that is animating the page, or increase the
[Code] TimeSlice parameter. If you cannot simplify the Cicode, you can create a separate task using
TaskNew() to calculate your complex operation, and then use the Display functions to display the
results. Cicode running from a TaskNew() call is in background mode and can run as long as required.

286 Out of Cicode threads

Citect has run out of Cicode tasks. Run fewer tasks (e.g. reports, key commands, and Cicode tasks) in
parallel, or increase the number of tasks with the [Code]Threads parameter. This error can be caused
by a configuration error if you keep creating tasks but do not "kill" them when they are no longer
required.

287 Floating point exception trap

An invalid floating-point number has been found. Check the floating-point data from the I/O Device.

288 Out of buffers

Citect is out of dynamic buffers. You have called a function that requests buffer space but no buffers
are available. Check which function is causing the error and increase the associated buffers, or slow
the rate of transfer to that function. If the error occurs on a server or LAN device, increase the number
of buffers with the [Lan]ReadPool parameter.
672 Cicode Errors

This error can also occur if something is stopping the release of the buffers, e.g. if network
communication has stopped or a PLC has just come off-line. The error 'Out of buffers' can also be
generated in the following ways:
1) Calling QueWrite() when the queue functions have run out of buffers. You can increase the
number of queue buffers with the [Code] Queue parameter.
2) Calling WinFree() to free the last Cicode window. If WinFree() did free the last window,
Citect would have no windows left.
To verify which function is causing the hardware error, display the {ERRPAGE} and {ERRDESC}
fields on the hardware alarm.

289 Name does not exist

The specified name does not exist in this context. You are probably using the wrong name.

290 Not finished

A request has been made for trend data that has not yet finished trending.

291 File not Citect format

The specified file is not in Citect format. The file (trend, graphic, or any other file) is in an invalid
format. Check that the name of the file is valid or that the file has not become corrupted.

292 Invalid function

The specified function name does not exist. You have tried to create a task, or called a remote
procedure, or set an event function that does not exist.

293 File error

A general file error has occurred. Either a general hardware error has occurred, or the operating
system is out of resources, or the file server is down.

294 File EOF

The end of the file was found. An attempt was made to read data off the end of a file or database.

295 Cicode stack overflow

A Cicode evaluation stack overflow has occurred. There are too many local function variables or
nested function calls. Reduce the number of local variables or increase the [Code] Stack parameter.
The Cicode stack is used to store local function variables and function calls. If you have many nested
functions and a large number of local function variables, the Cicode stack may overflow. When the
Cicode stack overflows, the Cicode that caused the overflow is halted.
 Cicode Errors 673

You can estimate the size of the stack by counting the maximum number of local function variables in
the deepest function calls. For example, if function A has 10 variables and calls function B with 30
variables, which calls function C with 40 variables, the stack needs to be 10 + 30 + 40 = 80 deep.

296 Queue empty

An attempt has been made to read an element from an empty queue.

297 Semaphore owner died

The owner of a Cicode semaphore was halted, killed, or returned without releasing the semaphore.
Reset the shared resource back to a known state (because the task that died may have left it in a mess),
and then continue. For example, if you are sharing a printer, do a form feed.

298 Semaphore timeout

The requested semaphore was still in use after the specified timeout. Either try to get the semaphore
again or abort the operation and tell the operator of the error.

299 Cancelled
The specified form or command was cancelled. This error is returned when a user presses the
[Cancel] button on a form. The normal procedure is to abort the operation.

300 Trend not found

The trend does not exist at the specified AN and page. A trend function may have been called when
the trend is not defined for that AN.

301 Trend pen not found

The required trend pen name does not exist in the Trends database or is not in the current user area.
Check that the pen name exists and check the current user's privilege and area.

302 Trend data not valid

The requested trend data is not valid. Either the I/O Device data was bad, or the Citect trend server
was shut down, or the trend data was disabled.

303 Invalid animation number

The AN specified in the function is not defined. You called one of the DspXXX animation functions,
but you specified an animation number that was out of range or that had been deleted.

304 File server failed, stand-by active

Citect has detected a file server fail condition, and will switch to the standby file server. The file
674 Cicode Errors

server is down due to failure of the network or of the file server computer. This error is displayed only
if you have enabled redundant file servers. If a redundant file server is not enabled, Citect and
Windows will crash when the file server fails. You should report this error to the operators - to fix the
file server.

305 Conflicting types of animation

The same AN is being used for two different types of animation. This error occurs if you try to display
two (or more) incompatible types of animation on the same AN (e.g. you try to display a symbol at a
AN where a bar graph is already displayed). Check the configuration. If you need to display a new
animation, you must first delete the old animation with the DspDel() function.

306 SQL field value truncated

A maximum of 1000bytes (1Kb) can be returned from a single field call. If the field data is larger than
this limit, it is truncated. You have tried to access a database where one of the fields is greater than
1000 bytes in size. Change the database field size to less than 1000 bytes so it can be accessed. In
fact, you should change the field size to less than 256 bytes, the maximum allowable length of a
Cicode string.

307 SQL database error

A general SQL error. Call the SQLErrMsg() function for details of the error.

308 SQL null field data returned

Data has been requested from a field that contained no data, or the SQL server does not support this
type of field data. Citect will return an empty string. Call the SQLFieldInfo() function to list the fields
in the database.

309 Trend data is gated

You have requested trend data that was gated (set to logging disabled) by the trigger expression (i.e.
when it was acquired). The data is returned with the gated values set to 0.

310 Incompatible server version

Two servers are running incompatible versions of the Citect software. Install the latest version on each
server. Contact Citect Support. to arrange for an upgrade.

311 Alarm tag synchronise error

When the Alarm server shuts down it writes an alarm save file. If the alarm server is in tag mode
(rather than record mode) this message will display. You can set the mode with the [Alarm]SaveStyle
parameter. You can ignore this message as it is a warning only.
 Cicode Errors 675

312 MAPI generic error

A generic MAPI error has occurred. Call the MailError() function to retrieve the MAPI error.

313 No MAPI
The MAPI mail system is not installed, or incorrectly installed on the computer.

314 MAPI offline

The computer is not logged on to the MAPI mail system. Call the MailLogon() function to log on to
the MAPI mail system.

315 MAPI no mail

No mail was available. This message is returned from the MailRead() function if no mail is available.

316 dBASE record locked by another

The dBASE file is being accessed by another user. Check if the dBASE file has been opened in
exclusive mode by the other user. This error can also occur if another user is updating the dBASE file,
and will most likely occur if it is an indexed database, and the file is on a slow file server. You can
adjust dBASE access with the [General]LockRetry and [General]LockDelay parameters.

317 Not in this version

The operation is not supported in this version of Citect. You must upgrade to a higher version.

318 Invalid page function

You have called the PageGoto(), PageNext(), PagePrev(), PageDisplay(), or PageLast() as an exit
command in the Pages database.

319 Low physical memory

Citect is low on physical memory. Increase available physical memory (not virtual memory). Reduce
the size of SMARTDRV cache, close any other windows programs that are running, or add more
RAM to your computer. You can set the minimum size of memory required by Citect with the
[Memory]MinPhyK parameter. This parameter sets a value for the minimum physical memory before
Citect will generate this error message.
This error may also occur if your swap file is very large (i.e. greater than 20Mb). Reduce the size of
your swap file. The swap file is configured with the Windows Control Panel (386 Enhanced icon).

320 Cannot free window

The WinFree() function has been called but Citect has no windows left. (Note that the last window
and any child windows owned by the last window cannot be removed.)
676 Cicode Errors

321 Font cannot be found

The specified font cannot be found. Check the font name.

322 LAN Failure

Citect has detected a failure on the network.

323 Super Genie not Associated

A Super Genie variable has not been associated correctly. This error can occur if a variable passed to
the Super Genie is the wrong data type or the variable does not exist. The error will also occur if the
Ass() function has not been called for the variable.

324 Transparent IO Device not Associated

A transparent I/O Device has not been correctly associated. Either the IODeviceControl() function
was not called before the page (with which the transparent device is associated) was displayed, or
incorrect data was passed to the I/O Device (such as the device name or protocol).

325 Project is not compiled

Changes have been made to the project while the system was running. Either restart the system or
shutdown and re-compile.

326 Could not run the Citect compiler

The Citect compiler could not be found. Either the computer has run out of memory, or the compiler
has been removed from its directory.

327 User Type not found

An attempt was made to create a user of a type that has not been defined in the users database.

328 User already exists

An attempt was made to create a new user with the same name as an existing user.

329 Cannot have mixed trends

An attempt was made to display both a periodic trend and an event trend in the same trend window.
Check the project configuration (Trend Tags and Page Trends databases) for mixed trends displayed in
a trend window.

336 Event type trend is expected

One of the arguments passed to this trend function is only valid for event type trends.
 Cicode Errors 677

337 Trend in file does not exist

The trend name inside the trend file does not exist in the trend database. It is very likely that the trend
file belongs to a trend which is deleted from the system configuration.

338 Plot Functions Sequence Mismatch

Plot functions are to be written in sequence since they depend on the data set up by other plot
functions. Please refer to the description section for each Plot Function for the order of plot functions.

339 Plot Marker is not Defined

An undefined plot marker symbol has been used. Use the PlotSetMarker function before the PlotLine,
PlotXYLine or PlotMarker functions.

342 Debug break

The DebugBreak() Cicode function has been called. This indicates an invalid condition detected in
user written Cicode. Enable the Cicode debugger to find the cause of the problem.

343 Foreground Cicode cannot break

A breakpoint has been hit in foreground Cicode. Foreground Cicode cannot be blocked. You can
disable this error message in Debug Options, accessed through the Debug menu in the Cicode Editor.

344 Format overflow

345 Trend data not ready

346 Dynamic Out of licence points

The dynamic point count has exceeded the point limit. Refer to the Citect Licence Point Count topic.

347 Assertion failed in user Cicode

An assertion has failed in your Cicode, and the task terminated. Assertions are made using the Assert()
function. If you set the [Code]DebugMessage parameter to 1, the assertion will be logged, and the
operator will be prompted.

354 Unrecognised object class

678 Cicode Errors

355 Object has no interface

356 Object automation exception

357 Too many arguments

358 Too few arguments

359 Named object already exists

360 Unrecognised named object

361 Page CTG/RDB record mismatch

362 Object event queue flooded

363 Incorrect number of arguments

364 No 'this' argument

1280 Socket error

 Cicode Errors 679

1330 WSAENETDOWN

1331 Socket unreachable

1332 Network reset

1333 Connection aborted

1334 Connection reset

1335 No buffers available

1340 Socket timeout

1341 Connection refused

1343 Name too long

1344 Host down

1345 Host unreachable

 Index

AlarmDsp function................................................160
AlarmDspLast function.........................................162
( AlarmDspNext function ........................................163
( ^ 50 AlarmDspPrev function ........................................164
( ^ ) caret character..................................................12 AlarmEnable function ...........................................165
formatting text strings .........................................50 AlarmEnableRec function.....................................167
in strings - using..................................................12 AlarmEventQue function ......................................168
( ^' ) escape sequence ..............................................50 AlarmFirstCatRec function ...................................168
( ^^ ) escape sequence .............................................50 AlarmFirstPriRec function ....................................169
( ^0xhh ) escape sequence .......................................50 AlarmFirstTagRec function...................................170
( ^b ) escape sequence .............................................50 AlarmGetDsp function ..........................................171
( ^f ) escape sequence..............................................50 AlarmGetFieldRec function ..................................172
( ^n ) escape sequence .............................................50 AlarmGetInfo function..........................................174
( ^r ) escape sequence..............................................50 AlarmGetThreshold function ................................175
( ^t ) escape sequence..............................................50 AlarmGetThresholdRec function ..........................176
( ^v ) escape sequence .............................................50 AlarmHelp function ..............................................177
AlarmNextCatRec function...................................177
AlarmNextPriRec function....................................179
_ AlarmNextTagRec function ..................................180
Alarms
_ObjectCallMethod function .................................145 Cicode functions ...............................................115
_ObjectGetProperty function ................................145 AlarmSetInfo function ..........................................181
_ObjectSetProperty function .................................146 AlarmSetQuery function .......................................183
AlarmSetThreshold function .................................185
A AlarmSetThresholdRec function...........................187
AlarmSplit function...............................................188
Abs function..........................................................146 AlarmSumAppend function ..................................188
AccControl function..............................................147 AlarmSumCommit function..................................189
ActiveX AlarmSumDelete function ....................................190
Cicode functions ...............................................115 AlarmSumFind function........................................191
Alarm Filtering AlarmSumFirst function........................................192
AlarmSetQuery .................................................183 AlarmSumGet function .........................................193
Implementing Query Functions ........................490 AlarmSumLast function ........................................194
Alarm functions.......................................................15 AlarmSumNext function .......................................195
AlarmAck function................................................147 AlarmSumPrev function........................................196
AlarmAckRec function .........................................150 AlarmSumSet function..........................................196
AlarmActive function............................................151 AlarmSumSplit function .......................................197
AlarmClear function..............................................152 AlarmSumType function.......................................198
AlarmClearRec function........................................154 AnByName function .............................................199
AlarmComment function.......................................155 ArcCos function ....................................................199
AlarmDelete function............................................155 ArcSin function.....................................................199
AlarmDisable function ..........................................157 ArcTan function ....................................................200
AlarmDisableRec function ....................................159 AreaCheck function ..............................................200
682 Index

arguments
Cicode functions – passing to............................. 11
B
multiple – in commands ....................................... 6 background Cicode..................................................64
passing to functions............................................ 11 backspace escape sequence .....................................50
arguments ............................................................... 11 Beep function ........................................................216
declaring data types............................................ 33 bit Operators............................................................53
default value setting ........................................... 35
key sequences as .................................................. 6
naming in functions............................................ 34 C
strings – using as ................................................ 12 calculations
structure ............................................................. 31 using variables in expressions...............................8
Arguments variables – using in expressions............................8
Array elements – using in .................................. 44 calculations
Array data type ....................................................... 43 variables in............................................................6
Arrays CallEvent function.................................................217
indexing ............................................................. 43 caret character ( ^ ) ..................................................12
initialising with values ....................................... 44 in strings - using..................................................12
Arrays Caret character ( ^ )
data type – declaring .......................................... 43 formatting ...........................................................50
properties ........................................................... 43 carriage return escape sequence ..............................50
Arrays CASE – see SELECT CASE statement...................60
using................................................................... 42 ChainEvent function..............................................219
Arrays ..................................................................... 42 CharToStr function................................................220
declaring............................................................. 43 Ci file extension ........................................................4
default values – setting....................................... 44 Cicode
elements – using in Arguments .......................... 44 variable arrays.....................................................42
Functions – using in ........................................... 46 Cicode
loops – using in .................................................. 46
bit logic ...............................................................53
naming ............................................................... 43 converting integers to strings ..............................47
single dimension – using.................................... 45 converting REAL to strings ................................47
size – declaring .................................................. 43 converting strings to integers ..............................48
Table Functions – using ..................................... 46
converting strings to REAL ................................48
three dimension – using ..................................... 45 converting to/from strings...................................46
two dimension – using ....................................... 45 escape sequences - using.....................................50
Ass function.......................................................... 201 SELECT CASE statement ..................................60
AssChain function ................................................ 201
Variables – formatting strings.............................46
AssChainPage function ........................................ 202 Cicode
AssChainPopUp function ..................................... 203 Alarm functions ..................................................15
AssChainWin function ......................................... 203 arguments – naming in functions ........................34
AssChainWinFree function .................................. 205 background tasks.................................................64
Assert function ..................................................... 206 bit Operators .......................................................53
AssInfo function ................................................... 207 calculations – performing with variables ..............6
AssPage function.................................................. 208 displaying data with expressions...........................8
AssPopUp function............................................... 209 expressions – decision making with......................8
AssScaleStr function ............................................ 211 expressions – triggering events with .....................9
AssTag function ................................................... 212 expressions – using variables in............................8
AssTitle function .................................................. 212 files – using...........................................................4
AssVarTags function ............................................ 213 function libraries .................................................21
AssWin function................................................... 214 functions - default argument value setting ..........35
functions – naming arguments in ........................34
groups of functions – writing ..............................21
 Index 683

introduction...........................................................3 functions - writing...............................................19

key sequences – using...........................................6 global Variable ...................................................40
keyboard functions..............................................16 how Citect executes ............................................63
logic ....................................................................54 IF statement ........................................................57
mathematical logic ..............................................51 local Variable......................................................42
multiple statements – using...................................6 logging expression data ........................................9
page functions.....................................................16 logical Operators.................................................54
programming logic..............................................51 mathematical Operators ......................................51
Programming Standard .......................................91 Modular Programming......................................101
relational logic ....................................................53 module Variable .................................................41
setting variables ....................................................5 multitasking ........................................................64
Standards for Labels ...........................................93 Programming Standards - Comments .................96
Standards for Variable Tags................................93 relational Operators ............................................53
Time/Date functions ...........................................17 Source File Headers............................................99
Variables - converting strings to REAL..............48 Standards for Constants, Variable Tags, &
variables – copying ...............................................5 Labels .............................................................93
variables - performing calculations with ...............6 statements – using multiple...................................6
variables – setting .................................................5 syntax..................................................................26
variables – using in expressions............................8 text - formatting in ..............................................48
Cicode Variable data types - declaring ...........................39
Assert function..................................................110 Variable Declaration Standards ..........................91
Cohesion ...........................................................102 Variable declaring...............................................39
Cohesion and Coupling Examples ....................104 Variable Naming Standards ................................92
commands - using .................................................4 Variable scope ....................................................40
conditional executors ..........................................57 Variable Scope Standards ...................................92
controlling tasks..................................................65 Variables - converting integers to strings............47
copying variables ..................................................5 Variables - converting REAL to strings..............47
Coupling ...........................................................103 Variables - converting strings to integers............48
data – displaying with expressions........................8 Variables - converting to/from strings ................46
data Operators.....................................................51 WHILE statement ...............................................59
Debug Error Trapping.......................................109 Cicode - See 'Cicode' below......................................3
debugging using comments.................................24 Cicode Debugger.....................................................67
DebugMsg function ..........................................109 Cicode Debugger.....................................................67
decision making with expressions.........................8 Cicode Editor ..........................................................67
Defensive Programming ...................................106 Cicode files ...............................................................4
Error Handling ..................................................107 using .....................................................................4
event handling.....................................................63 Cicode functions
event triggering with expressions..........................9 declaring argument data types ...........................33
expressions - using................................................8 Cicode functions
files .....................................................................21 ActiveX.............................................................115
FOR statement ....................................................58 Alarms ................................................................15
foreground tasks..................................................64 argument passing ...............................................11
Formatting Executable Statements......................95 argument structure .............................................31
Formatting Expressions ......................................96 debugging using comments ................................24
Formatting Functions..........................................97 scope...................................................................27
Formatting Simple Declarations .........................94 structure ..............................................................19
Function Headers ..............................................100 syntax..................................................................26
Function Naming Standards................................98 trigonometrical..................................................130
function structure ................................................19 Cicode functions
functions - returning values from........................37 _ObjectCallMethod...........................................145
functions - using..................................................10 _ObjectGetProperty ..........................................145
684 Index

_ObjectSetProperty .......................................... 146 ArcSin ...............................................................199

Abs ................................................................... 146 ArcTan ..............................................................200
AccControl....................................................... 147 AreaCheck ........................................................200
AlarmAck......................................................... 147 Ass ....................................................................201
AlarmAckRec .................................................. 150 AssChain...........................................................201
AlarmActive..................................................... 151 AssChainPage ...................................................202
AlarmClear....................................................... 152 AssChainPopUp................................................203
AlarmClearRec ................................................ 154 AssChainWin ....................................................203
AlarmComment................................................ 155 AssChainWinFree .............................................205
AlarmDelete ..................................................... 155 Assert ................................................................206
AlarmDisable ................................................... 157 AssInfo..............................................................207
AlarmDisableRec ............................................. 159 AssPage.............................................................208
AlarmDsp......................................................... 160 AssPopUp .........................................................209
AlarmDspLast .................................................. 162 AssScaleStr .......................................................211
AlarmDspNext ................................................. 163 AssTag ..............................................................212
AlarmDspPrev.................................................. 164 AssTitle.............................................................212
AlarmEnable .................................................... 165 AssVarTags.......................................................213
AlarmEnableRec .............................................. 167 AssWin .............................................................214
AlarmEventQue ............................................... 168 Beep ..................................................................216
AlarmFirstCatRec ............................................ 168 CallEvent ..........................................................217
AlarmFirstPriRec ............................................. 169 ChainEvent .......................................................219
AlarmFirstTagRec............................................ 170 CharToStr .........................................................220
AlarmGetDsp ................................................... 171 CitectColourToPackedRGB..............................220
AlarmGetFieldRec ........................................... 172 CitectInfo ..........................................................220
AlarmGetInfo ................................................... 174 clipboard ...........................................................117
AlarmGetThreshold ......................................... 175 ClipCopy...........................................................225
AlarmGetThresholdRec ................................... 176 ClipPaste ...........................................................225
AlarmHelp........................................................ 177 ClipReadLn.......................................................226
AlarmNextCatRec ............................................ 177 ClipSetMode .....................................................226
AlarmNextPriRec............................................. 179 ClipWriteLn ......................................................227
AlarmNextTagRec ........................................... 180 Cluster...............................................................117
alarms............................................................... 115 ClusterGetName................................................227
AlarmSetInfo.................................................... 181 ClusterSetName ................................................228
AlarmSetQuery ................................................ 183 CodeSetMode....................................................229
AlarmSetThreshold .......................................... 185 CodeTrace.........................................................231
AlarmSetThresholdRec .................................... 187 colour ................................................................117
AlarmSplit........................................................ 188 ComClose .........................................................232
AlarmSumAppend ........................................... 188 communication..................................................117
AlarmSumCommit ........................................... 189 ComOpen..........................................................232
AlarmSumDelete.............................................. 190 ComRead ..........................................................234
AlarmSumFind................................................. 191 ComReset..........................................................235
AlarmSumFirst................................................. 192 ComWrite .........................................................235
AlarmSumGet .................................................. 193 Cos ....................................................................237
AlarmSumLast ................................................. 194 CreateControlObject .........................................237
AlarmSumNext ................................................ 195 CreateObject .....................................................239
AlarmSumPrev................................................. 196 Date...................................................................240
AlarmSumSet ................................................... 196 DateAdd............................................................241
AlarmSumSplit ................................................ 197 DateDay ............................................................241
AlarmSumType................................................ 198 DateMonth ........................................................242
AnByName ...................................................... 199 DateSub.............................................................242
ArcCos ............................................................. 199 DateWeekDay...................................................243
 Index 685

DateYear ...........................................................244 DspAnCreateControlObject..............................274

DDE ..................................................................118 DspAnFree........................................................275
DDEExec ..........................................................245 DspAnGetArea .................................................275
DDEhExecute ...................................................245 DspAnGetPos ...................................................276
DDEhGetLastError ...........................................246 DspAnGetPrivilege...........................................276
DDEhInitiate.....................................................247 DspAnInfo ........................................................277
DDEhPoke ........................................................248 DspAnInRgn.....................................................278
DDEhRequest ...................................................249 DspAnMove .....................................................278
DDEhTerminate................................................249 DspAnMoveRel ................................................279
DDEPost ...........................................................250 DspAnNew .......................................................279
DDERead..........................................................250 DspAnNewRel..................................................280
DDEWrite .........................................................251 DspBar..............................................................280
DebugBreak ......................................................252 DspBmp............................................................281
DebugMsg.........................................................252 DspButton.........................................................282
DebugMsgSet ...................................................253 DspButtonFn.....................................................283
declaring .............................................................29 DspChart...........................................................284
declaring return type ...........................................28 DspCol..............................................................285
DegToRad.........................................................253 DspDel..............................................................286
DevAppend .......................................................254 DspDelayRenderBegin .....................................286
DevClose ..........................................................254 DspDelayRenderEnd ........................................287
DevControl .......................................................255 DspDirty ...........................................................288
DevCurr ............................................................255 DspError ...........................................................288
DevDelete .........................................................256 DspFile .............................................................289
DevDisable .......................................................256 DspFileGetInfo .................................................290
DevEOF ............................................................257 DspFileGetName ..............................................290
DevFind ............................................................257 DspFileScroll....................................................291
DevFirst ............................................................258 DspFileSetName ...............................................291
DevFlush...........................................................259 DspFont ............................................................292
DevGetField......................................................259 DspFontHnd .....................................................293
DevHistory........................................................260 DspFullScreen ..................................................294
devices ..............................................................119 DspGetAnBottom .............................................295
DevInfo .............................................................260 DspGetAnCur ...................................................295
DevModify........................................................262 DspGetAnExtent...............................................296
DevNext............................................................263 DspGetAnFromPoint ........................................297
DevOpen ...........................................................263 DspGetAnHeight ..............................................298
DevPrev ............................................................265 DspGetAnLeft ..................................................298
DevPrint............................................................266 DspGetAnRight ................................................299
DevRead ...........................................................266 DspGetAnTop...................................................299
DevReadLn .......................................................267 DspGetAnWidth ...............................................299
DevRecNo.........................................................267 DspGetEnv .......................................................300
DevSeek............................................................268 DspGetMouse ...................................................300
DevSetField ......................................................268 DspGetNearestAn .............................................301
DevSize.............................................................269 DspGetParentAn ...............................................301
DevWrite ..........................................................269 DspGetSlider ....................................................302
DevWriteLn ......................................................270 DspGetTip ........................................................302
DevZap .............................................................271 DspGrayButton.................................................303
display...............................................................120 DspInfo .............................................................303
DLL ..................................................................123 DspInfoDestroy ................................................305
DLLCall............................................................271 DspInfoField.....................................................306
DLLClose .........................................................272 DspInfoNew......................................................307
DLLOpen..........................................................272 DspInfoValid ....................................................308
686 Index

DspIsButtonGray ............................................. 308 file.....................................................................124

DspKernel ........................................................ 309 FileClose ...........................................................345
DspMarkerMove .............................................. 309 FileCopy ...........................................................345
DspMarkerNew................................................ 310 FileDelete..........................................................346
DspMCI ........................................................... 311 FileEOF.............................................................346
DspPlaySound.................................................. 312 FileExist............................................................347
DspRichText .................................................... 313 FileFind.............................................................347
DspRichTextEdit.............................................. 314 FileGetTime ......................................................348
DspRichTextEnable ......................................... 314 FileMakePath....................................................348
DspRichTextGetInfo ........................................ 315 FileOpen ...........................................................349
DspRichTextLoad ............................................ 315 FilePrint ............................................................350
DspRichTextPgScroll....................................... 316 FileRead............................................................350
DspRichTextPrint............................................. 317 FileReadBlock ..................................................351
DspRichTextSave............................................. 317 FileReadLn .......................................................351
DspRichTextScroll........................................... 318 FileRename .......................................................352
DspRubEnd...................................................... 319 FileRichTextPrint..............................................352
DspRubMove ................................................... 319 FileSeek ............................................................353
DspRubSetClip ................................................ 320 FileSetTime.......................................................354
DspRubStart..................................................... 320 FileSize .............................................................354
DspSetSlider .................................................... 321 FileSplitPath .....................................................354
DspSetTip ........................................................ 322 FileWrite ...........................................................355
DspSetTooltipFont ........................................... 322 FileWriteBlock..................................................355
DspStatus ......................................................... 323 FileWriteLn.......................................................356
DspStr .............................................................. 324 FmtClose...........................................................384
DspSym............................................................ 324 FmtFieldHnd.....................................................357
DspSymAnm.................................................... 325 FmtGetField ......................................................357
DspSymAnmEx ............................................... 326 FmtGetFieldHnd ...............................................358
DspSymAtSize ................................................. 328 FmtOpen ...........................................................358
DspText............................................................ 329 FmtSetField.......................................................359
DspTipMode .................................................... 329 FmtSetFieldHnd................................................359
DspTrend ......................................................... 330 FmtToStr...........................................................360
DspTrendInfo ................................................... 332 form ..................................................................125
DumpKernel..................................................... 333 FormActive .......................................................360
EngToGeneric .................................................. 333 FormAddList.....................................................361
EnterCriticalSection ......................................... 334 format................................................................126
ErrCom............................................................. 335 FormButton.......................................................361
ErrDrv .............................................................. 335 FormCheckBox.................................................362
ErrGetHw......................................................... 336 FormComboBox ...............................................363
ErrHelp............................................................. 337 FormCurr ..........................................................365
ErrInfo.............................................................. 337 FormDestroy .....................................................365
ErrLog.............................................................. 338 FormEdit ...........................................................366
ErrMsg ............................................................. 338 FormField .........................................................367
error.................................................................. 123 FormGetCurrInst...............................................369
ErrSet ............................................................... 339 FormGetData ....................................................369
ErrSetHw ......................................................... 339 FormGetInst ......................................................370
ErrSetLevel ...................................................... 340 FormGetText.....................................................371
ErrTrap............................................................. 341 FormGoto..........................................................371
events ............................................................... 123 FormGroupBox.................................................372
Exec ................................................................. 342 FormInput .........................................................373
Exp................................................................... 344 FormListAddText .............................................373
Fact .................................................................. 344 FormListBox.....................................................374
 Index 687

FormListDeleteText..........................................375 HighByte...........................................................406
FormListSelectText ..........................................376 HighWord .........................................................406
FormNew ..........................................................377 I/O Devices .......................................................128
FormNumPad....................................................378 InfoForm...........................................................407
FormOpenFile...................................................379 InfoFormAn ......................................................408
FormPassword ..................................................380 Input..................................................................408
FormPosition.....................................................380 IntToReal..........................................................409
FormPrompt......................................................381 IntToStr.............................................................410
FormRadioButton .............................................382 IODeviceControl ..............................................410
FormRead .........................................................383 IODeviceInfo ....................................................413
FormSaveAsFile ...............................................384 IODeviceStats...................................................414
FormSelectPrinter .............................................385 IsError...............................................................415
FormSetData .....................................................385 KerCmd ............................................................415
FormSetInst.......................................................386 KeyAllowCursor...............................................415
FormSetText .....................................................386 keyboard ...........................................................129
FormWndHnd ...................................................387 keyboard - using .................................................16
FTP ...................................................................126 KeyBs ...............................................................416
FTPClose ..........................................................388 KeyDown..........................................................417
FTPFileCopy.....................................................388 KeyGet..............................................................417
FTPFileFind......................................................389 KeyGetCursor...................................................418
FTPOpen...........................................................390 KeyLeft.............................................................418
FullName ..........................................................390 KeyMove ..........................................................419
FuzzyClose .......................................................390 KeyPeek............................................................419
FuzzyGetCodeValue.........................................391 KeyPut ..............................................................420
FuzzyGetShellValue .........................................391 KeyPutStr .........................................................420
FuzzyOpen ........................................................392 KeyReplay ........................................................421
FuzzySetCodeValue..........................................393 KeyReplayAll ...................................................421
FuzzySetShellValue..........................................393 KeyRight...........................................................421
FuzzyTech.........................................................126 KeySetCursor....................................................422
FuzzyTrace .......................................................394 KeySetSeq ........................................................422
GetArea.............................................................394 KeyUp ..............................................................423
GetBlueValue ...................................................395 LanguageFileTranslate......................................423
GetEnv ..............................................................395 LeaveCriticalSection.........................................424
GetEvent ...........................................................395 Ln425
GetGreenValue .................................................398 Log....................................................................425
GetPriv..............................................................398 Login ................................................................425
GetRedValue.....................................................399 LoginForm........................................................426
group.................................................................128 Logout ..............................................................427
groups of – writing..............................................21 LogoutIdle ........................................................427
GrpClose ...........................................................399 LowByte ...........................................................428
GrpDelete..........................................................399 LowWord..........................................................428
GrpFirst.............................................................400 mail...................................................................129
GrpIn.................................................................401 MailError ..........................................................429
GrpInsert ...........................................................401 MailLogoff .......................................................429
GrpMath............................................................402 MailLogon ........................................................429
GrpName ..........................................................403 MailRead ..........................................................430
GrpNext ............................................................403 MailSend...........................................................431
GrpOpen ...........................................................404 mathematical.....................................................130
GrpToStr ...........................................................405 Max...................................................................432
Halt ...................................................................405 Message ............................................................433
HexToStr ..........................................................406 Min ...................................................................433
688 Index

miscellaneous................................................... 131 PlotInfo .............................................................469

MsgBrdcst ........................................................ 434 PlotLine.............................................................470
MsgClose ......................................................... 434 PlotMarker ........................................................472
MsgGetCurr ..................................................... 435 PlotOpen ...........................................................474
MsgOpen.......................................................... 435 PlotScaleMarker................................................477
MsgRead .......................................................... 436 PlotSetMarker ...................................................478
MsgRPC........................................................... 437 PlotText.............................................................478
MsgWrite ......................................................... 439 PlotXYLine.......................................................479
Name................................................................ 440 Pow ...................................................................482
naming ............................................................... 30 Print ..................................................................482
ObjectAssociateEvents..................................... 440 PrintFont ...........................................................483
ObjectByName................................................. 441 PrintLn ..............................................................484
OnEvent ........................................................... 441 PRIVATE & PUBLIC scope ..............................27
outlining ............................................................. 21 ProjectRestartGet ..............................................484
PackedRGB...................................................... 444 ProjectRestartSet...............................................484
PackedRGBToCitectColour............................. 445 ProjectSet..........................................................485
page.................................................................. 132 Prompt ..............................................................485
Page Popup....................................................... 456 Pulse..................................................................486
PageAlarm........................................................ 445 QueClose...........................................................486
PageDisabled.................................................... 446 QueLength ........................................................487
PageDisplay ..................................................... 447 QueOpen ...........................................................487
PageFile ........................................................... 448 QuePeek............................................................488
PageFileInfo..................................................... 449 QueRead ...........................................................489
PageGetInt........................................................ 449 Query Functions................................................490
PageGetStr ....................................................... 450 QueWrite...........................................................491
PageGoto.......................................................... 450 RadToDeg.........................................................492
PageHardware .................................................. 451 Rand..................................................................492
PageInfo ........................................................... 451 RealToStr..........................................................492
PageLast........................................................... 452 RepGetControl ..................................................493
PageMenu ........................................................ 453 Report ...............................................................494
PageNext .......................................................... 454 reports ...............................................................133
PagePeekLast ................................................... 455 RepSetControl...................................................495
PagePopLast..................................................... 456 ReRead..............................................................497
PagePrev .......................................................... 457 returning data ......................................................14
PagePushLast ................................................... 458 Round................................................................498
PageRichTextFile............................................. 458 security..............................................................134
pages - using ...................................................... 16 SemClose ..........................................................498
PageSelect ........................................................ 460 SemOpen...........................................................498
PageSetInt ........................................................ 461 SemSignal .........................................................499
PageSetStr........................................................ 461 SemWait ...........................................................499
PageSummary .................................................. 461 SendKeys ..........................................................500
PageTrend ........................................................ 462 SerialKey ..........................................................502
ParameterGet.................................................... 463 ServerInfo .........................................................503
ParameterPut .................................................... 464 SetArea .............................................................505
PathToStr ......................................................... 464 SetEvent............................................................505
Pi 465 SetLanguage .....................................................508
plot ................................................................... 133 Shutdown ..........................................................509
PlotClose.......................................................... 465 ShutdownForm..................................................510
PlotDraw .......................................................... 465 ShutdownMode.................................................511
PlotGetMarker.................................................. 467 Sign...................................................................511
PlotGrid............................................................ 467 Sin.....................................................................512
 Index 689

Sleep .................................................................512 Super Genie ......................................................127

SleepMS............................................................513 SwitchConfig ....................................................557
SPCPlot.............................................................519 syntax - following ...............................................24
SPCSetLimit .....................................................522 SysTime............................................................557
SQL...................................................................135 SysTimeDelta ...................................................558
SQLAppend ..............................................342, 526 table ..................................................................137
SQLBeginTran..................................................527 TableLookup.....................................................559
SQLCommit......................................................528 TableMath.........................................................559
SQLConnect .....................................................529 TableShift .........................................................560
SQLDisconnect.................................................531 TagDebug .........................................................561
SQLEnd ............................................................532 TagInfo .............................................................561
SQLErrMsg.......................................................533 TagRamp ..........................................................562
SQLExec...........................................................533 TagRead............................................................563
SQLFieldInfo ....................................................537 TagScaleStr.......................................................564
SQLGetField.....................................................538 TagWrite...........................................................565
SQLInfo ............................................................539 Tan....................................................................566
SQLNext ...........................................................540 TaskGetSignal ..................................................567
SQLNoFields ....................................................540 TaskHnd ...........................................................567
SQLNumChange...............................................541 TaskKill ............................................................568
SQLRollBack....................................................541 TaskNew...........................................................568
SQLSet..............................................................542 TaskResume......................................................570
SQLTraceOff ....................................................543 tasks ..................................................................137
SQLTraceOn.....................................................543 TaskSetSignal ...................................................570
Sqrt ...................................................................543 TaskSuspend.....................................................571
StrClean ............................................................544 TestRandomWave.............................................571
StrFill................................................................544 TestSawWave ...................................................572
StrFormat ..........................................................545 TestSinWave.....................................................573
StrGetChar ........................................................545 TestSquareWave ...............................................573
string .................................................................136 TestTriangWave ...............................................574
StrLeft...............................................................546 Time..................................................................575
StrLength ..........................................................546 time/date ...........................................................138
StrLower ...........................................................546 Time/Date - using ...............................................17
StrMid...............................................................547 TimeCurrent......................................................575
StrPad................................................................547 TimeHour .........................................................576
StrRight.............................................................548 TimeMidNight ..................................................577
StrSearch...........................................................548 TimeMin ...........................................................577
StrSetChar.........................................................549 TimeSec............................................................578
StrToChar .........................................................549 TimeSet.............................................................578
StrToDate..........................................................550 TimeToStr.........................................................580
StrToFmt...........................................................550 Toggle...............................................................581
StrToGrp ...........................................................551 TraceMsg..........................................................581
StrToHex ..........................................................551 trend..................................................................139
StrToInt.............................................................552 TrendDspCursorScale.......................................582
StrToLocalText.................................................553 TrendDspCursorTag .........................................582
StrToPeriod.......................................................553 TrendDspCursorTime .......................................582
StrToReal..........................................................554 TrendDspCursorValue......................................583
StrToTime.........................................................554 TrendGetAn ......................................................583
StrToValue........................................................555 TrendPopUp......................................................584
StrTrim..............................................................555 TrendRun..........................................................584
StrUpper............................................................556 TrendSetDate ....................................................585
StrWord ............................................................556 TrendSetScale...................................................585
690 Index

TrendSetSpan................................................... 586 TrnSamplesConfigured .....................................628

TrendSetTime .................................................. 586 TrnScroll ...........................................................628
TrendSetTimebase ........................................... 587 TrnSelect...........................................................629
TrendWin ......................................................... 587 TrnSetCursor.....................................................630
TrendZoom ...................................................... 589 TrnSetCursorPos...............................................630
TrnAddHistory ................................................. 590 TrnSetDisplayMode..........................................631
TrnClientInfo ................................................... 590 TrnSetEvent ......................................................632
TrnComparePlot............................................... 591 TrnSetPen .........................................................633
TrnDelete ......................................................... 593 TrnSetPenFocus ................................................633
TrnDelHistory .................................................. 593 TrnSetPeriod .....................................................634
TrnEcho ........................................................... 593 TrnSetScale.......................................................635
TrnEventGetTable............................................ 594 TrnSetSpan .......................................................636
TrnEventGetTableMS ...................................... 596 TrnSetTable ......................................................636
TrnEventSetTable ............................................ 597 TrnSetTime .......................................................638
TrnEventSetTableMS....................................... 598 UserCreate ........................................................638
TrnExportClip .................................................. 599 UserCreateForm................................................639
TrnExportCSV ................................................. 601 UserDelete ........................................................639
TrnExportDBF ................................................. 602 UserEditForm....................................................640
TrnFlush........................................................... 603 UserInfo ............................................................640
TrnGetBufEvent............................................... 604 UserPassword....................................................641
TrnGetBufTime................................................ 604 UserPasswordForm ...........................................641
TrnGetBufValue............................................... 605 Version..............................................................641
TrnGetCursorEvent.......................................... 606 WhoAmI ...........................................................642
TrnGetCursorMSTime ..................................... 606 WinCopy...........................................................642
TrnGetCursorPos ............................................. 607 window .............................................................141
TrnGetCursorTime........................................... 607 WinFile .............................................................643
TrnGetCursorValue.......................................... 608 WinFree ............................................................643
TrnGetCursorValueStr ..................................... 609 WinGetFocus ....................................................644
TrnGetDefScale ............................................... 609 WinGetWndHnd ...............................................644
TrnGetDisplayMode ........................................ 610 WinGoto ...........................................................644
TrnGetEvent..................................................... 610 WinMode ..........................................................645
TrnGetFormat .................................................. 611 WinMove ..........................................................646
TrnGetGatedValue ........................................... 612 WinNew............................................................646
TrnGetInvalidValue ......................................... 612 WinNewAt ........................................................647
TrnGetMode..................................................... 613 WinNext............................................................649
TrnGetMSTime................................................ 613 WinNumber ......................................................649
TrnGetPen ........................................................ 615 WinPos..............................................................650
TrnGetPenFocus............................................... 615 WinPrev ............................................................650
TrnGetPenNo ................................................... 616 WinPrint............................................................651
TrnGetPeriod.................................................... 616 WinPrintFile .....................................................652
TrnGetScale ..................................................... 617 WinSelect..........................................................654
TrnGetScaleStr................................................. 617 WinSize.............................................................655
TrnGetSpan ...................................................... 618 WinTitle............................................................655
TrnGetTable..................................................... 619 WndFind ...........................................................656
TrnGetTime...................................................... 621 WndGetFileProfile............................................656
TrnGetUnits ..................................................... 623 WndGetProfile ..................................................657
TrnInfo ............................................................. 623 WndHelp...........................................................657
TrnIsValidValue............................................... 624 WndInfo............................................................659
TrnNew ............................................................ 625 WndPutFileProfile ............................................660
TrnPlot ............................................................. 625 WndPutProfile ..................................................661
TrnPrint............................................................ 626 WndShow .........................................................661
 Index 691

WndViewer.......................................................662 ClusterSetName function ......................................228

Cicode Functions CodeSetMode function..........................................229
Array elements in Arguments - using .................44 CodeTrace function...............................................231
using arrays.........................................................42 Colour ...................................................................117
Cicode Functions Cicode functions ...............................................117
event handling.....................................................63 ComClose function ...............................................232
FOR statement ....................................................58 command
IF statement ........................................................57 FOR statement ....................................................58
SELECT CASE statement ..................................60 IF statement ........................................................57
Variable declaring...............................................39 SELECT CASE statement ..................................60
WHILE statement ...............................................59 WHILE statement ...............................................59
Cicode Functions commands
how Citect executes ............................................63 conditional ..........................................................57
multitasking ........................................................64 commands .................................................................4
TaskNew .............................................................65 commands
Cicode Standards.....................................................91 Cicode - using.......................................................4
Debug Error Trapping.......................................109 Cicode execute......................................................4
Introduction.........................................................91 FOR statement ....................................................58
Cicode Standards IF statement ........................................................57
Constants ............................................................93 keyboard sequence – using ...................................6
Labels..................................................................93 multiple statements in ...........................................6
Variable Tags......................................................93 SELECT CASE statement ..................................60
Cicode Standards strings – using in.................................................12
Cohesion ...........................................................102 WHILE statement ...............................................59
Cohesion and Coupling Examples ....................104 comments
Comments ...........................................................96 debugging Cicode – using in...............................24
Coupling ...........................................................103 pseudocode .........................................................22
Defensive Programming ...................................106 comments ................................................................22
Error Handling ..................................................107 Comments
Formatting Executable Statements......................95 Cicode file headers .............................................22
Formatting Expressions ......................................96 in Cicode.............................................................23
Formatting Functions..........................................97 common ..................................................................15
Formatting Simple Declarations .........................94 Communication
Function Headers ..............................................100 Functions ..........................................................117
Function Naming ................................................98 Communication
Modular Programming......................................101 Cicode functions ...............................................117
Source File Headers ............................................99 Communication Functions ....................................117
Variable Declaration ...........................................91 ComOpen function................................................232
Variable Naming.................................................92 ComRead function ................................................234
Variable Scope....................................................92 ComReset function................................................235
Cicode: ......................................................................3 ComWrite function ...............................................235
CitectColourToPackedRGB function ....................220 concatenating ..........................................................48
CitectInfo function ................................................220 conditional executors ..............................................57
Clipboard...............................................................117 Constants
Cicode functions ...............................................117 Cicode Standards ................................................93
ClipCopy function .................................................225 copying......................................................................5
ClipPaste function .................................................225 copying variables ......................................................5
ClipReadLn function .............................................226 Cos function ..........................................................237
ClipSetMode function ...........................................226 CreateControlObject function ...............................237
ClipWriteLn function ............................................227 CreateObject function ...........................................239
ClusterGetName function......................................227
692 Index

Debugger .................................................................67
D debugging
data comments in – using ...........................................24
type – return declaring ....................................... 28 DebugMsg function...............................................252
data DebugMsgSet function..........................................253
declaring return type .......................................... 28 decision making ........................................................8
data ........................................................................... 5 declaring
bit Operators....................................................... 53 Array size............................................................43
copying variables ................................................. 5 Variable data types - declaring............................39
displaying with expressions ................................. 8 declaring
expression – logging ............................................ 9 Array data types ..................................................43
logging expressions.............................................. 9 Array names........................................................43
logical Operators ................................................ 54 Arrays .................................................................43
mathematical Operators ..................................... 51 Variables .............................................................39
Operators............................................................ 51 declaring..................................................................29
relational Operators............................................ 53 arguments data types...........................................33
setting values........................................................ 5 Cicode functions .................................................29
triggering events with........................................... 9 Declaring Variables
data types................................................................ 39 Cicode Standard..................................................91
Arrays................................................................. 43 default
data types Array values - setting ..........................................44
declaring............................................................. 39 default......................................................................35
declaring function arguments ............................. 33 default
data types Variable values – setting.....................................40
DIGITAL .......................................................... 39 Defensive Programming
INT..................................................................... 39 Cicode Standards ..............................................106
OBJECT............................................................. 39 DegToRad function ...............................................253
REAL ................................................................. 39 DevAppend function .............................................254
STRING ............................................................. 39 DevClose function.................................................254
Date function ........................................................ 240 DevControl function..............................................255
DateAdd function ................................................. 241 DevCurr function...................................................255
DateDay function ................................................. 241 DevDelete function ...............................................256
DateMonth function.............................................. 242 DevDisable function..............................................256
DateSub function.................................................. 242 DevEOF function ..................................................257
DateWeekDay function ........................................ 243 DevFind function...................................................257
DateYear function ................................................ 244 DevFirst function...................................................258
DDE...................................................................... 118 DevFlush function .................................................259
Cicode functions .............................................. 118 DevGetField function............................................259
DDEExec function ............................................... 245 DevHistory function..............................................260
DDEhExecute function......................................... 245 Devices..................................................................119
DDEhGetLastError function................................. 246 Cicode functions ...............................................119
DDEhInitiate function .......................................... 247 DevInfo function ...................................................260
DDEhPoke function.............................................. 248 DevModify function..............................................262
DDEhRequest function......................................... 249 DevNext function ..................................................263
DDEhTerminate function ..................................... 249 DevOpen function .................................................263
DDEPost function................................................. 250 DevPrev function...................................................265
DDERead function ............................................... 250 DevPrint function ..................................................266
DDEWrite function .............................................. 251 DevRead function..................................................266
Debug Error Trapping DevReadLn function .............................................267
Cicode Standards.............................................. 109 DevRecNo function...............................................267
DebugBreak function............................................ 252 DevSeek function ..................................................268
 Index 693

DevSetField function.............................................268 DspFont function...................................................292

DevSize function...................................................269 DspFontHnd function............................................293
DevWrite function.................................................269 DspFullScreen function.........................................294
DevWriteLn function ............................................270 DspGetAnBottom function ...................................295
DevZap function....................................................271 DspGetAnCur function .........................................295
DIGITAL data type...............................................39 DspGetAnExtent function.....................................296
dimension DspGetAnFromPoint function ..............................297
Array size declaration elements DspGetAnHeight function ....................................298
number of .......................................................43 DspGetAnLeft function.........................................298
dimension ................................................................43 DspGetAnRight function ......................................299
dimension DspGetAnTop function.........................................299
single - using.......................................................45 DspGetAnWidth function .....................................299
three - using ........................................................45 DspGetEnv function..............................................300
two - using ..........................................................45 DspGetMouse function .........................................300
Display ..................................................................120 DspGetNearestAn function ...................................301
Cicode functions ...............................................120 DspGetParentAn function .....................................301
displaying data ..........................................................8 DspGetSlider function...........................................302
DLLCall function ..................................................271 DspGetTip function...............................................302
DLLClose function................................................272 DspGrayButton function .......................................303
DLLOpen function ................................................272 DspInfo function ...................................................303
DO – see FOR statement .........................................58 DspInfoDestroy function.......................................305
DO – see WHILE statement ....................................59 DspInfoField function ...........................................306
double quotes ( ........................................................50 DspInfoNew function............................................307
double quotes ( ........................................................12 DspInfoValid function ..........................................308
DspAnCreateControlObject function ....................274 DspIsButtonGray function ....................................308
DspAnFree function ..............................................275 DspKernel function ...............................................309
DspAnGetArea function........................................275 DspMarkerMove function.....................................309
DspAnGetPos function..........................................276 DspMarkerNew function.......................................310
DspAnGetPrivilege function .................................276 DspMCI function ..................................................311
DspAnInfo function...............................................277 DspPlaySound function.........................................312
DspAnInRgn function ...........................................278 DspRichText function ...........................................313
DspAnMove function............................................278 DspRichTextEdit function ....................................314
DspAnMoveRel function ......................................279 DspRichTextEnable function ................................314
DspAnNew function..............................................279 DspRichTextGetInfo function...............................315
DspAnNewRel function ........................................280 DspRichTextLoad function...................................315
DspBar function ....................................................280 DspRichTextPgScroll function .............................316
DspBmp function ..................................................281 DspRichTextPrint function ...................................317
DspButton function ...............................................282 DspRichTextSave function ...................................317
DspButtonFn function ...........................................283 DspRichTextScroll function..................................318
DspChart function .................................................284 DspRubEnd function.............................................319
DspCol function ....................................................285 DspRubMove function..........................................319
DspDel function ....................................................286 DspRubSetClip function .......................................320
DspDelRenderBegin function ...............................286 DspRubStart function............................................320
DspDelRenderEnd function ..................................287 DspSetSlider function ...........................................321
DspDirty function..................................................288 DspSetTip function ...............................................322
DspError function..................................................288 DspSetTooltipFont function..................................322
DspFile function....................................................289 DspStatus function ................................................323
DspFileGetInfo function .......................................290 DspStr function .....................................................324
DspFileGetName function.....................................290 DspSym function...................................................324
DspFileScroll function ..........................................291 DspSymAnm function...........................................325
DspFileSetName function .....................................291 DspSymAnmEx function ......................................326
694 Index

DspSymAtSize function ....................................... 328 ( ^n )....................................................................50

DspText function.................................................. 329 ( ^r ) ....................................................................50
DspTipMode function .......................................... 329 ( ^t ).....................................................................50
DspTrend function................................................ 330 ( ^v )....................................................................50
DspTrendInfo function ......................................... 332 backspace ............................................................50
DumpKernel function........................................... 333 carriage return .....................................................50
Dynamic Linked Libraries.................................... 123 character..............................................................50
Cicode functions .............................................. 123 form feed.............................................................50
in strings - using..................................................12
new line...............................................................50
E tab .......................................................................50
editing..................................................................... 67 evaluating
editing functions .............................................................11
Cicode ................................................................ 67 evaluating ................................................................11
Editor...................................................................... 67 event handling .........................................................63
Editor events
Cicode ................................................................ 67 handling ..............................................................63
Debugger............................................................ 67 triggering with expressions ...................................9
elements Events....................................................................123
Arguments – using in ......................................... 44 Cicode functions ...............................................123
elements.................................................................. 42 Exec function ........................................................342
data type – declaring .......................................... 43 Executable Statements
elements Formatting Standards ..........................................95
loops – using in .................................................. 46 ExecuteDTSPkg function ......................................342
END statement ....................................................... 19 executing
END Statement....................................................... 29 function structure ................................................19
EngToGeneric function ........................................ 333 executors ...................................................................4
EnterCriticalSection function ............................... 334 Cicode commands.................................................4
ErrCom function................................................... 335 conditional ..........................................................57
ErrDrv function .................................................... 335 how Citect executes ............................................63
ErrGetHw function ............................................... 336 multitasking ........................................................64
ErrHelp function................................................... 337 Exp function..........................................................344
ErrInfo function.................................................... 337 Expression Formatting
ErrLog function .................................................... 338 Cicode Standard..................................................96
ErrMsg function ................................................... 338 expressions ................................................................8
Error Handling expressions
Cicode Standards.............................................. 107 Cicode – using ......................................................8
Errors.................................................................... 123 data – displaying with ...........................................8
Cicode functions .............................................. 123 decision making with ............................................8
ErrSet function ..................................................... 339 logging data ..........................................................9
ErrSetHw function................................................ 339 mathematics in ......................................................8
ErrSetLevel function ............................................ 340 triggering events with ...........................................9
ErrTrap function ................................................... 341 using......................................................................8
escape sequences .................................................... 50 variables in............................................................8
escape sequences
( ^ 50
( ^' ) .................................................................... 50
F
( ^^ ) ................................................................... 50 Fact function..........................................................344
( ^0xhh )............................................................. 50 FALSE
( ^b )................................................................... 50 logical - decision making with expressions...........8
( ^f ) ................................................................... 50
 Index 695

logical – triggering events with strings .................................................................50

expressions .......................................................9 text ................................................................46, 50
FileClose function .................................................345 Formatting Executable Statements
FileCopy function..................................................345 Cicode Standards ................................................95
FileDelete function................................................346 Formatting Expressions
FileEOF function...................................................346 Cicode Standards ................................................96
FileExist function ..................................................347 Formatting Functions
FileFind function...................................................347 Cicode Standards ................................................97
FileGetTime function ............................................348 Formatting Simple Declarations
FileMakePath function ..........................................348 Cicode Standards ................................................94
FileOpen function..................................................349 FormButton function.............................................361
FilePrint function ..................................................350 FormCheckBox function.......................................362
FileRead function ..................................................350 FormComboBox function .....................................363
FileReadBlock function.........................................351 FormCurr function ................................................365
FileReadLn function..............................................351 FormDestroy function ...........................................365
FileRename function .............................................352 FormEdit function .................................................366
FileRichTextPrint function....................................352 FormField function ...............................................367
files..........................................................................21 FormGetCurrInst function.....................................369
files............................................................................4 FormGetData function ..........................................369
Ci extension ..........................................................4 FormGetInst function............................................370
Cicode – using ......................................................4 FormGetText function...........................................371
Cicode function source files................................21 FormGoto function................................................371
Files.......................................................................124 FormGroupBox function.......................................372
Cicode functions ...............................................124 FormInput function ...............................................373
FileSeek function ..................................................353 FormListAddText function ...................................373
FileSetTime function.............................................354 FormListBox function...........................................374
FileSize function ...................................................354 FormListDeleteText function................................375
FileSplitPath function............................................354 FormListSelectText function.................................376
FileWrite function .................................................355 FormNew function ................................................377
FileWriteBlock function........................................355 FormNumPad function..........................................378
FileWriteLn function.............................................356 FormOpenFile function.........................................379
FmtClose function .................................................384 FormPassword function ........................................380
FmtFieldHnd function ...........................................357 FormPosition function...........................................380
FmtGetField function ............................................357 FormPrompt function............................................381
FmtGetFieldHnd function .....................................358 FormRadioButton function ...................................382
FmtOpen function .................................................358 FormRead function ...............................................383
FmtSetField function.............................................359 Forms ....................................................................125
FmtSetFieldHnd function ......................................359 Cicode functions ...............................................125
FmtToStr function .................................................360 FormSaveAsFile function .....................................384
FOR statement.........................................................58 FormSelectPrinter function ...................................385
foreground Cicode...................................................64 FormSetData function ...........................................385
form feed escape sequence ......................................50 FormSetInst function.............................................386
FormActive function .............................................360 FormSetText function ...........................................386
FormAddList function...........................................361 FormWndHnd function .........................................387
Format ...................................................................126 FTP
Cicode functions ...............................................126 Cicode functions ...............................................126
Format Operator ( FTPClose function ................................................388
) 47 FTPFileCopy function...........................................388
formatting................................................................50 FTPFileFind function............................................389
string Variables...................................................46 FTPOpen function.................................................390
formatting Full Screen
696 Index

DspFullScreen.................................................. 294 combining with statements..................................11

FullName function................................................ 390 Command – using in ...........................................10
function files........................................................... 21 multiple arguments..............................................13
Function Formatting numeric arguments..............................................14
Cicode Standard ................................................. 97 performing ..........................................................10
Function Headers variable arguments ..............................................14
Cicode Standards.............................................. 100 Functions
Function Naming Array elements – using in ...................................44
Cicode Standard ................................................. 98 using arrays .........................................................42
function outlines ..................................................... 21 Functions
FUNCTION statement............................................ 19 Cicode – converting integers to strings ...............47
FUNCTION Statement........................................... 29 Cicode – converting REAL to strings .................47
FunctionName( )..................................................... 30 Cicode – converting strings to integers ...............48
functions Cicode – converting strings to REAL .................48
declaring return type .......................................... 28 how Citect executes ............................................63
headers ............................................................... 22 multitasking ........................................................64
pre-built.............................................................. 19 Variable declaring...............................................39
returning data ..................................................... 14 Functions
functions Arrays – using in.................................................46
Cicode built-in ................................................... 10 Cicode – converting to/from strings....................46
commonly used .................................................. 15 converting integers to strings ..............................47
evaluating........................................................... 11 converting REAL to strings ................................47
naming ............................................................... 30 converting strings to integers ..............................48
PUBLIC scope ................................................... 27 converting strings to REAL ................................48
returning values from ......................................... 37 converting to/from strings...................................46
syntax ................................................................. 26 event handling.....................................................63
syntax following................................................. 24 formatting strings ................................................46
functions Table Array Functions – using............................46
argument structure............................................. 31 TaskNew .............................................................65
arguments........................................................... 11 Functions
arguments – naming ........................................... 34 SPCPlot.............................................................519
caret ( ^ ) escape sequences................................ 12 Fuzzy Logic...........................................................126
debugging using comments................................ 24 FuzzyClose function..............................................390
declaring............................................................. 29 FuzzyGetCodeValue function ...............................391
declaring argument data types........................... 33 FuzzyGetShellValue function ...............................391
default argument value setting ........................... 35 FuzzyOpen function ..............................................392
END statement ................................................... 19 FuzzySetCodeValue function................................393
expressions – using in ....................................... 10 FuzzySetShellValue function ................................393
files .................................................................... 21 FuzzyTech
FUNCTION statement ....................................... 19 Cicode functions ...............................................126
libraries .............................................................. 21 FuzzyTrace function..............................................394
naming ............................................................... 19
naming arguments in .......................................... 34
outlinng .............................................................. 21 G
PRIVATE scope................................................. 27 GetArea function...................................................394
scope .................................................................. 27 GetBlueValue function..........................................395
storage.................................................................. 4 GetEnv function ....................................................395
string arguments - using ..................................... 12 GetEvent function .................................................395
structure ............................................................. 19 GetGreenValue function........................................398
writing Cicode.................................................... 19 GetPriv function ....................................................398
functions GetRedValue function...........................................399
 Index 697

global.......................................................................40 INT data type ..........................................................39

Variables.............................................................40 INT data type
Graphs ...................................................................133 converting to strings ...........................................47
Groups converting to/from strings...................................46
Cicode functions ...............................................128 IntToReal function ................................................409
GrpClose function .................................................399 IntToStr function...................................................410
GrpDelete function................................................399 IODeviceControl function.....................................410
GrpFirst function...................................................400 IODeviceInfo function ..........................................413
GrpIn function.......................................................401 IODeviceStats function .........................................414
GrpInsert function .................................................401 IsError function.....................................................415
GrpMath function..................................................402
GrpName function.................................................403
GrpNext function ..................................................403 K
GrpOpen function..................................................404 KerCmd function...................................................415
GrpToStr function .................................................405 key sequences............................................................6
arguments – using as.............................................6
H KeyAllowCursor function.....................................415
Keyboard...............................................................129
Halt function .........................................................405 Cicode functions ...............................................129
handling events........................................................63 keyboard functions..................................................16
headers ....................................................................22 KeyBs function .....................................................416
headers KeyDown function................................................417
in Cicode files .....................................................22 KeyGet function....................................................417
Headers (Function) KeyGetCursor function .........................................418
Cicode Standard................................................100 KeyLeft function...................................................418
Headers (Source File) KeyMove function ................................................419
Cicode Standard..................................................99 KeyPeek function..................................................419
HexToStr function.................................................406 KeyPut function ....................................................420
HighByte function .................................................406 KeyPutStr function................................................420
HighWord function ...............................................406 KeyReplay function ..............................................421
KeyReplayAll function .........................................421
KeyRight function.................................................421
I KeySetCursor function..........................................422
I/O Devices ...........................................................128 KeySetSeq function...............................................422
Cicode functions ...............................................128 KeyUp function.....................................................423
icode
commonly used functions ...................................15
IF statement.............................................................57
L
indexing Labels
Arguments – using Array elements in.................44 Cicode Standards ................................................93
Array declaring ...................................................43 LanguageFileTranslate function............................423
indexing...................................................................43 LeaveCriticalSection function...............................424
indexing libraries ...................................................................21
Array elements....................................................43 libraries
InfoForm function .................................................407 Cicode functions .................................................21
InfoFormAn function ............................................408 Ln function............................................................425
initialising................................................................44 local.........................................................................42
initialising Variables.............................................................42
Arrays .................................................................44 Log function..........................................................425
Input function ........................................................408 logging
698 Index

data - expressions ................................................. 9 Coupling ...........................................................103

expression data..................................................... 9 module.....................................................................41
logic Variables .............................................................41
FOR statement ................................................... 58 MsgBrdcst function ...............................................434
IF statement........................................................ 57 MsgClose function ................................................434
looping ............................................................... 57 MsgGetCurr function ............................................435
WHILE statement .............................................. 59 MsgOpen function.................................................435
logic........................................................................ 54 MsgRead function .................................................436
decision making with expressions........................ 8 MsgRPC function..................................................437
expressions – decision making with ..................... 8 MsgWrite function ................................................439
expressions – triggering events with .................... 9 multiple arguments..................................................13
SELECT CASE statement.................................. 60 multitasking.............................................................64
triggering events with expressions ....................... 9 foreground...........................................................64
logical Operators .................................................... 54 multitasking
Login function ...................................................... 425 background .........................................................64
LoginForm function.............................................. 426 controlling tasks..................................................65
Logout function .................................................... 427 multitasking
LogoutIdle function .............................................. 427 preemptive ..........................................................65
loops ....................................................................... 57
FOR statement ................................................... 58
IF statement........................................................ 57 N
SELECT CASE statement.................................. 60 Name function.......................................................440
WHILE statement .............................................. 59 naming
LowByte function................................................. 428 Arrays .................................................................43
LowWord function ............................................... 428 naming
arguments in functions........................................34
M functions .......................................................19, 30
naming.....................................................................40
Mail ...................................................................... 129 Naming Functions
Cicode functions .............................................. 129 Cicode Standards ................................................98
MailError function................................................ 429 naming Variables.....................................................40
MailLogoff function ............................................. 429 Naming Variables
MailLogon function.............................................. 429 Cicode Standard..................................................92
MailRead function ................................................ 430 new line escape sequence ........................................50
MailSend function ................................................ 431 numeric arguments ..................................................14
making
logic decisions with expressions .......................... 8
mathematical Operators.......................................... 51 O
mathematics OBJECT data type...................................................39
data – displaying with expressions................... 8, 9 ObjectAssociateEvents function............................440
expressions – using .............................................. 8 ObjectByName function........................................441
expressions – using in ...................................... 8, 9 OnEvent function ..................................................441
variables – calculations with ................................ 6 Operator
variables – using in expressions ........................... 8 Format (
Max function ........................................................ 432 ) 47
Message function.................................................. 433 operator input ............................................................6
Min function......................................................... 433 getting ...................................................................6
Modular Programming key sequences as arguments..................................6
Cicode Standards.............................................. 101 operator input
Cohesion .......................................................... 102 using....................................................................14
Cohesion and Coupling Examples ................... 104
 Index 699

Operators Pi function.............................................................465
logical .................................................................54 PlotClose function.................................................465
Operators.................................................................51 PlotDraw function .................................................465
bit 53 PlotGetMarker function ........................................467
conditional executors ..........................................57 PlotGrid function...................................................467
data .....................................................................51 PlotInfo function ...................................................469
FOR statement ....................................................58 PlotLine function...................................................470
IF statement ........................................................57 PlotMarker function ..............................................472
mathematical.......................................................51 PlotOpen function .................................................474
relational .............................................................53 Plots ......................................................................133
SELECT CASE statement ..................................60 Cicode functions ...............................................133
WHILE statement ...............................................59 PlotScaleMarker function......................................477
overview....................................................................3 PlotSetMarker function .........................................478
Cicode...................................................................3 PlotText function...................................................478
PlotXYLine function.............................................479
Pow function .........................................................482
P preemptive multitasking..........................................65
PackedRGB function.............................................444 Print function ........................................................482
PackedRGBToCitectColour function ....................445 PrintFont function .................................................483
page functions .........................................................16 PrintLn function ....................................................484
Page Popup function..............................................456 PRIVATE................................................................27
Page Size function scope.....................................................27
FullScreen function...........................................294 scope in functions ...............................................27
PageAlarm function...............................................445 programming
PageDisabled function...........................................446 bit logic...............................................................53
PageDisplay function ............................................447 bit Operators .......................................................53
PageFile function ..................................................448 Cicode commands.................................................4
PageFileInfo function............................................449 data Operators.....................................................51
PageGetInt function...............................................449 decision making with expressions ........................8
PageGetStr function ..............................................450 expressions - decision making with ......................8
PageGoto function.................................................450 FOR statement ....................................................58
PageHardware function .........................................451 function argument structure ...............................31
PageInfo function ..................................................451 function argument types.....................................33
PageLast function..................................................452 function arguments .............................................11
PageMenu function ...............................................453 function declaring ...............................................29
PageNext function .................................................454 function naming..................................................30
PagePeekLast function ..........................................455 function structure................................................19
PagePopLast function............................................456 function syntax ...................................................26
PagePrev function .................................................457 IF statement ........................................................57
PagePushLast function ..........................................458 logic ..............................................................51, 54
PageRichTextFile function....................................458 logic decision making with expressions................8
Pages .....................................................................132 logical Operators.................................................54
Cicode functions ...............................................132 loops - using .......................................................57
PageSelect function ...............................................460 mathematical logic..............................................51
PageSetInt function ...............................................461 mathematical Operators ......................................51
PageSetStr function ...............................................461 relational logic ....................................................53
PageSummary function .........................................461 relational Operators ............................................53
PageTrend function ...............................................462 SELECT CASE statement ..................................60
ParameterGet function...........................................463 variables – copying ...............................................5
ParameterPut function ...........................................464 variables – setting .................................................5
PathToStr function ................................................464 WHILE statement ...............................................59
700 Index

Programming Standard ........................................... 91 Round function......................................................498

ProjectRestartGet function ................................... 484
ProjectRestartSet function .................................... 484
ProjectSet function ............................................... 485 S
Prompt function.................................................... 485 scope
pseudocode ............................................................. 22 global ............................................................40, 41
PUBLIC.................................................................. 27 local ....................................................................42
function scope .................................................... 27 PRIVATE function .............................................27
scope in functions............................................... 27 scope .......................................................................40
Pulse function ....................................................... 486 functions .............................................................27
PUBLIC function................................................27
Q Variables .............................................................40
Security .................................................................134
QueClose function................................................ 486 Cicode functions ...............................................134
QueLength function.............................................. 487 SELECT CASE Statement ......................................60
QueOpen function ................................................ 487 SemClose function ................................................498
QuePeek function ................................................. 488 SemOpen function.................................................498
QueRead function................................................. 489 SemSignal function ...............................................499
Query Functions SemWait function..................................................499
Implementing Query Functions........................ 490 SendKeys function ................................................500
QueWrite function ................................................ 491 SerialKey function.................................................502
Quote character ServerInfo function ...............................................503
escape sequence ................................................. 50 SetArea function....................................................505
Quotes ( ' ................................................................ 12 SetEvent function ..................................................505
SetLanguage function............................................508
setting
R argument default values ......................................35
RadToDeg function .............................................. 492 setting........................................................................5
Rand function ....................................................... 492 one variable to another's value ..............................5
REAL data type ...................................................... 39 variables................................................................5
REAL data type Shutdown ..............................................................509
converting to strings........................................... 47 Shutdown function ................................................509
converting to/from strings .................................. 46 ShutdownForm function........................................510
RealToStr function ............................................... 492 ShutdownMode function .......................................511
relational Operators ................................................ 53 Sign function .........................................................511
RepGetControl function ....................................... 493 Sin function ...........................................................512
Report function..................................................... 494 single quotes ( ' ) .....................................................50
Reports ................................................................. 133 Sleep function........................................................512
Cicode functions .............................................. 133 SleepMS function..................................................513
RepSetControl function ........................................ 495 Source File Headers
ReRead function ................................................... 497 Cicode Standards ................................................99
Resizing pages source files ..............................................................21
FullScreen function .......................................... 294 SPC .......................................................................134
return SPCAlarms............................................................514
returning data ..................................................... 14 SPCClientInfo .......................................................516
return SPCGetHistogramTable ........................................517
declaring type..................................................... 28 SPCGetSubgroupTable .........................................518
returning ................................................................. 37 SPCPlot function...................................................519
returning SPCProcessXRSGet ..............................................520
values from functions......................................... 37 SPCProcessXRSSet...............................................521
SPCSetLimit function ...........................................522
 Index 701

SPCSpecLimitGet .................................................523 StrFill function ......................................................544

SPCSpecLimitSet ..................................................524 StrFormat function ................................................545
SPCSubgroupSizeGet............................................525 StrGetChar function ..............................................545
SPCSubgroupSizeSet ............................................525 string arguments......................................................12
special characters ....................................................50 STRING data type...................................................39
SQL .......................................................................135 STRING data type
Cicode functions ...............................................135 converting strings to integers ..............................48
SQLAppend function ............................................526 converting strings to REAL ................................48
SQLBeginTran function ........................................527 converting to/from strings...................................46
SQLCommit function............................................528 strings
SQLConnect function............................................529 caret character ( ^ ) – using in.............................12
SQLDisconnect function .......................................531 strings......................................................................48
SQLEnd function ..................................................532 arguments - using as ...........................................12
SQLErrMsg function.............................................533 assignment in commands ....................................12
SQLExec function .................................................533 concatenating......................................................48
SQLFieldInfo function ..........................................537 converting to integers .........................................48
SQLGetField function ...........................................538 converting to numbers ........................................46
SQLInfo function ..................................................539 converting to REAL............................................48
SQLNext function .................................................540 double quotes – using in .....................................12
SQLNoFields function ..........................................540 escape sequences in ............................................50
SQLNumChange function.....................................541 formatting ...........................................................48
SQLRollBack function..........................................541 Strings ...................................................................136
SQLSet function....................................................542 Cicode functions ...............................................136
SQLTraceOff function ..........................................543 StrLeft function.....................................................546
SQLTraceOn function ...........................................543 StrLength function ................................................546
Sqrt function..........................................................543 StrLower function .................................................546
Standards.................................................................91 StrMid function.....................................................547
statements................................................................11 StrPad function......................................................547
combining ...........................................................11 StrRight function...................................................548
combining with functions ...................................11 StrSearch function.................................................548
command - using...................................................4 StrSetChar function...............................................549
comments in functions ........................................19 StrToChar function ...............................................549
copying variables in ..............................................5 StrToDate function................................................550
END ..............................................................19, 29 StrToFmt function.................................................550
FUNCTION ..................................................19, 29 StrToGrp function .................................................551
function naming ..................................................19 StrToHex function.................................................551
multiple – using ....................................................6 StrToInt function...................................................552
setting variables in ................................................5 StrToLocalText function.......................................553
variables – copying in ...........................................5 StrToPeriod function.............................................553
variables – setting .................................................5 StrToReal function................................................554
Statements StrToTime function...............................................554
SELECT CASE...................................................60 StrToValue function..............................................555
Variable declaring...............................................39 StrTrim function....................................................555
Statements StrUpper function..................................................556
conditional ..........................................................57 StrWord function...................................................556
FOR ....................................................................58 Super Genies
IF 57 Cicode functions ...............................................127
repetitive/reiterative ............................................57 SwitchConfig function ..........................................557
WHILE ...............................................................59 syntax ......................................................................26
Statistical Process Control.....................................134 following.............................................................24
StrClean function ..................................................544 SysTime function ..................................................557
702 Index

SysTimeDelta function......................................... 558 TimeMin function .................................................577

TimeSec function ..................................................578
TimeSet function...................................................578
T TimeToStr function ...............................................580
tab escape sequence................................................ 50 Toggle function .....................................................581
TableLookup function .......................................... 559 TraceMsg function ................................................581
TableMath function .............................................. 559 TrendDspCursorScale function .............................582
Tables ................................................................... 137 TrendDspCursorTag function................................582
Cicode functions .............................................. 137 TrendDspCursorTime function .............................582
TableShift function............................................... 560 TrendDspCursorValue function ............................583
TagDebug function............................................... 561 TrendGetAn function ............................................583
TagInfo function................................................... 561 TrendPopUp function............................................584
TagRamp function................................................ 562 TrendRun function ................................................584
TagRead function ................................................. 563 Trends....................................................................139
TagScaleStr function ............................................ 564 Cicode functions ...............................................139
TagWrite function ................................................ 565 TrendSetDate function ..........................................585
Tan function ......................................................... 566 TrendSetScale function .........................................585
TaskGetSignal function ........................................ 567 TrendSetSpan function..........................................586
TaskHnd function ................................................. 567 TrendSetTime function..........................................586
TaskKill function.................................................. 568 TrendSetTimebase function...................................587
TaskNew function .................................................. 65 TrendWin function ................................................587
TaskNew function ................................................ 568 TrendZoom function .............................................589
TaskResume function ........................................... 570 triggers ......................................................................9
tasks expressions – using ...............................................9
controlling.......................................................... 65 TrnAddHistory function ........................................590
how Citect executes ........................................... 63 TrnClientInfo function ..........................................590
tasks TrnComparePlot function......................................591
background......................................................... 64 TrnDelete function ................................................593
foreground.......................................................... 64 TrnDelHistory function .........................................593
multitasking........................................................ 64 TrnEcho function...................................................593
preemptive multitasking..................................... 65 TrnEventGetTable function...................................594
Tasks .................................................................... 137 TrnEventGetTableMS function .............................596
Cicode functions .............................................. 137 TrnEventSetTable function ...................................597
TaskSetSignal function......................................... 570 TrnEventSetTableMS function..............................598
TaskSuspend function .......................................... 571 TrnExportClip function .........................................599
TestRandomWave function .................................. 571 TrnExportCSV function ........................................601
TestSawWave function......................................... 572 TrnExportDBF function ........................................602
TestSinWave function .......................................... 573 TrnFlush function..................................................603
TestSquareWave function..................................... 573 TrnGetBufEvent function......................................604
TestTriangWave function ..................................... 574 TrnGetBufTime function.......................................604
text.......................................................................... 48 TrnGetBufValue function......................................605
text TrnGetCursorEvent function .................................606
formatting........................................................... 48 TrnGetCursorMSTime function ............................606
threads .................................................................... 63 TrnGetCursorPos function ....................................607
Time function ....................................................... 575 TrnGetCursorTime function..................................607
Time/Date............................................................. 138 TrnGetCursorValue function.................................608
Cicode functions .............................................. 138 TrnGetCursorValueStr function ............................609
Time/Date functions ............................................... 17 TrnGetDefScale function ......................................609
TimeCurrent function ........................................... 575 TrnGetDisplayMode function ...............................610
TimeHour function ............................................... 576 TrnGetEvent function............................................610
TimeMidNight function........................................ 577 TrnGetFormat function..........................................611
 Index 703

TrnGetGatedValue function ..................................612 Array default - setting.........................................44

TrnGetInvalidValue function ................................612 values
TrnGetMode function............................................613 default .................................................................40
TrnGetMSTime function.......................................613 returning from functions .....................................37
TrnGetPen function ...............................................615 values ........................................................................5
TrnGetPenFocus function......................................615 copying .................................................................5
TrnGetPenNo function ..........................................616 default – setting arguments in functions .............35
TrnGetPeriod function...........................................616 setting ...................................................................5
TrnGetScale function ............................................617 setting Variable default.......................................40
TrnGetScaleStr function........................................617 setting variables ....................................................5
TrnGetSpan function .............................................618 Variable Declaration
TrnGetTable function............................................619 Cicode Standards ................................................91
TrnGetTime function.............................................621 Variable Naming
TrnGetUnits function ............................................623 Cicode Standards ................................................92
TrnInfo function ....................................................623 Variable Scope
TrnIsValidValue function......................................624 Cicode Standards ................................................92
TrnNew function ...................................................625 Variable Tags
TrnPlot function ....................................................625 Cicode Standards ................................................93
TrnPrint function...................................................626 variables
TrnSamplesConfigured function ...........................628 calculations with ...................................................6
TrnScroll function .................................................628 copying .................................................................5
TrnSelect function .................................................629 setting ...................................................................5
TrnSetCursor function...........................................630 Variables
TrnSetCursorPos function .....................................630 global ............................................................40, 41
TrnSetDisplayMode function ................................631 local ....................................................................42
TrnSetEvent function ............................................632 Variables
TrnSetPen function................................................633 Array – naming...................................................43
TrnSetPenFocus function ......................................633 Array data type – declaring.................................43
TrnSetPeriod function ...........................................634 Array elements – number of ...............................43
TrnSetScale function .............................................635 Array size – declaring.........................................43
TrnSetSpan function..............................................636 arrays ..................................................................42
TrnSetTable function.............................................636 declaring .............................................................39
TrnSetTime function .............................................638 declaring data types ............................................39
TRUE default values – setting .......................................40
logical - decision making with expressions...........8 naming ................................................................40
logical - triggering events with expressions ..........9 scope – global ...............................................40, 41
scope – local .......................................................42
using arrays.........................................................42
U Variables
UserCreate function...............................................638 converting integers to strings ..............................47
UserCreateForm function ......................................639 converting REAL to strings ................................47
UserDelete function...............................................639 converting strings to integers ..............................48
UserEditForm function..........................................640 converting strings to REAL ................................48
UserInfo function ..................................................640 converting to/from strings...................................46
UserPassword function..........................................641 formatting strings................................................46
UserPasswordForm function .................................641 Global, Module and Local ..................................40
scope...................................................................40
setting default values ..........................................40
V Version function....................................................641
values
704 Index

W
WHILE statement................................................... 59
WhoAmI function................................................. 642
WinCopy function ................................................ 642
Windows............................................................... 141
Cicode functions .............................................. 141
WinFile function................................................... 643
WinFree function.................................................. 643
WinGetFocus function.......................................... 644
WinGetWndHnd function..................................... 644
WinGoto function................................................. 644
WinMode function ............................................... 645
WinMove function ............................................... 646
WinNew function ................................................. 646
WinNewAt function ............................................. 647
WinNext function ................................................. 649
WinNumber function............................................ 649
WinPos function ................................................... 650
WinPrev function ................................................. 650
WinPrint function ................................................. 651
WinPrintFile function........................................... 652
WinSelect function ............................................... 654
WinSize function.................................................. 655
WinTitle function ................................................. 655
WndFind function................................................. 656
WndGetFileProfile function ................................. 656
WndGetProfile function ....................................... 657
WndHelp function ................................................ 657
WndInfo function ................................................. 659
WndPutFileProfile function.................................. 660
WndPutProfile function........................................ 661
WndShow function............................................... 661
WndViewer function ............................................ 662
writing .................................................................... 19
writing
Cicode functions ................................................ 19
Writing
groups of functions............................................. 21