Using Cicode Functions Page 1 of 5

Cicode Programming Reference > Using Cicode Functions

file:///C:/Users/gilbertojunior/AppData/Local/Temp/~hh7A06.htm 25/03/2019
Using Cicode Functions Page 2 of 5

Using Cicode Functions

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

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
Cicode Programming Reference > Using Cicode Functions > Triggering Functions via Runtime Operator Input

Triggering Functions via Runtime Operator Input

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

Key Sequence Page_Down

Command PageNext();
Cicode Programming Reference > Using Cicode Functions > Evaluating Functions

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"

Note: Functions return a value that indicates the success of the function, or provides information on an
error that has occurred. In many cases (for example, when used in a command) the return value can be
ignored. You need to use the parentheses () in the function name, even if the function uses no arguments.
Function names are not case-sensitive: PageNext(), pagenext() and PAGENEXT() call the same function.

Cicode Programming Reference > Using Cicode Functions > Combining Functions with Other Statements

Combining Functions with Other Statements

In expressions and commands you can use functions alone or in combination with other functions, operators,
and so on.

file:///C:/Users/gilbertojunior/AppData/Local/Temp/~hh7A06.htm 25/03/2019
Using Cicode Functions Page 3 of 5

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 specific control over your processes,
for example, you can test for abnormal operating conditions and act on them.
Cicode Programming Reference > Using Cicode Functions > Passing Data to Functions (Arguments)

Passing Data to Functions (Arguments)

The parentheses ( ) in the function name identify the statement as a function and enclose its arguments.
Arguments are the values or variables that are passed into the function when it executes.

Note: Some functions (such as PageNext()) have no arguments. However you need to include the
parentheses ( ) or Vijeo Citect will not recognize that it is a function, and an error could result when the
project is compiled.

Cicode Programming Reference > Using Cicode Functions > Using String Arguments

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ʺ. Be aware that when you pass a string to a function,
you need to 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");

Cicode Programming Reference > Using Cicode Functions > Using String Arguments > String assignment

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 need to enclose a string in double quotation marks ( ʺ ).

Cicode Programming Reference > Using Cicode Functions > Using the Caret Escape Sequence Character

Using the Caret Escape Sequence Character

The caret character ( ^ ) signifies a special instruction in Cicode, called an escape sequence, primarily used in

file:///C:/Users/gilbertojunior/AppData/Local/Temp/~hh7A06.htm 25/03/2019
Using Cicode Functions Page 4 of 5

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

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

sCurrentAlmText = "Thermal Overload";

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

Cicode Programming Reference > Using Cicode Functions > Using Multiple Arguments

Using Multiple Arguments

Some functions require several arguments. You need to list 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 affects 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.
Cicode Programming Reference > Using Cicode Functions > Using Numeric Arguments

Using Numeric Arguments

You can pass numbers (integers and floating point numbers) directly to a function, for example:

Command AlarmAck(2, 35);

Cicode Programming Reference > Using Cicode Functions > Using Variable Arguments

Using Variable Arguments

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

Command DspStr(25, "TextFont", B1_TIC_101_PV);

In this instance, the value of B1_TIC_101_PV displays. If it is a real-time variable, the number that displays
depends on its value at the time.

Note: If you use double quotes around variables, for example, ʺB1_TIC_101_PVʺ, the text string
B1_TIC_101_PV displays, rather than the value of the variable.

Cicode Programming Reference > Using Cicode Functions > Using Operator Input in Functions

file:///C:/Users/gilbertojunior/AppData/Local/Temp/~hh7A06.htm 25/03/2019
Using Cicode Functions Page 5 of 5

Using Operator Input in Functions

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

Key Sequence F10 ######## Enter

Command PageDisplay(Arg1);

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

Cicode Programming Reference > Using Cicode Functions > Returning Data from Functions

Returning Data from Functions

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

Numeric expression Date();

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

On page entry Prompt("Hello, " + FullName())

For example, if the current user is John Citizen, the message ʺHello, John Citizenʺ displays.

file:///C:/Users/gilbertojunior/AppData/Local/Temp/~hh7A06.htm 25/03/2019