Program Variables in IEC
See also: IEC 61131 Language Editor Programming
See also: Enhanced IEC 61131 Guide
Topic Menu
Note: All variables used in programs must be first declared in the Program Variables Window. Each variable belongs to a group and is must be identified by a unique name within its group.
Groups - Variables in IEC
A group is a set of variables. A group either refers to a physical class of variables, or identifies the variables local to a program or user defined function block. Below are the possible groups:
GLOBAL |
Internal variables known by all programs |
RETAIN |
No- volatile internal variables known by all programs |
PROGRAMxxx |
All internal variables local to a program (the name of the group is the name of the program) |
Constant Expressions
Constant expressions can be used in all languages for assigning a variable with a value. All constant expressions have a well defined data type according to their semantics. If the user programs an operation between variables and constant expressions having inconsistent data types, it will lead to syntactic errors when the program is compiled.
Below are the syntactic rules for constant expressions according to possible data types:
BOOL Boolean- [Data Type BOOL] - A single bit, binary value, or register/variable. Boolean points have only two possible values, 'TRUE' or 'FALSE'.: Boolean- There are only two possible Boolean constant expressions. They are reserved keywords TRUE and FALSE.
SINT Short Integer [Data Type SINT] - An 8-bit signed value. Short Integers are used where the value of the data is expected to be in the range of -128 to +127.: Small (8 bit) Integer - Small integer constant expressions are valid integer values (between -128 and 127) and must be prefixed with "SINT#'. All integer expressions having no prefix are considered as DINT Double Integer - [Data Type DINT] - A 32-bit signed value. Double Integers are used where the value of the data is expected to be in the range of -2,147,483,648 to +2,147,483,647. integers.
USINT Unsigned Short Integer - [Data Type USINT] - An 8-bit unsigned value. Unsigned Short Integers are used where the value of the data is expected to be in the range of 0 (zero) to 255. / BYTE Byte - [Data Type BYTE] - A string of 8 consecutive bits. A single BYTE is also the size of a single ASCII character.: Unsigned 8 bit Integer - Unsigned small integer constant expressions are valid integer values (between 0 and 255) and must be prefixed with "USINT#'. All integer expressions having no prefix are considered as DINT integers.
INT Integer - [Data Type INT] - A 16-bit signed value. Integers are used where the value of the data is expected to be in the range of -32,768 to +32,767.: 16 bit integer - 16 bit integer constant expressions are valid integer values (between -32768 and 32767) and must be prefixed with "INT#'. All integer expressions having no prefix are considered as DINT integers.
UINT Unsigned Integer - [Data Type UINT] - A 16-bit unsigned value. Unsigned Integers are used where the value of the data is expected to be in the range of -0 (zero) to 65,535. / WORD: Unsigned 16 bit integer - Unsigned 16 bit integer constant expressions are valid integer values (between 0 and 65535) and must be prefixed with "UINT#'. All integer expressions having no prefix are considered as DINT integers.
DINT Double Integer - [Data Type DINT] - A 32-bit signed value. Double Integers are used where the value of the data is expected to be in the range of -2,147,483,648 to +2,147,483,647.: 32 bit (default) integer - 32 bit integer constant expressions must be valid numbers between -2147483648 to +2147483647. DINT is the default size for integers: such constant expressions do not need any prefix. The user can use "2#", "8#" or "16#" prefixes for specifying a number in respectively binary, octal or hexadecimal A base-16 numbering system which uses the symbols 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F for numeral. basis.
UDINT Unsigned Double Integer - [Data Type UDINT] - A 32-bit unsigned value. Unsigned Double Integers are used where the value of the data is expected to be in the range of 0 (zero) to 4,294,967,296. / DWORD DWORD - [Data Type DWORD] - A string of 32 consecutive bits. DWORD values are used where the value of the data is not as important as the bit patterns (shifts and rotates).: Unsigned 32 bit integer - Unsigned 32 bit integer constant expressions are valid integer values (between 0 and 4294967295) and must be prefixed with "UDINT#'. All integer expressions having no prefix are considered as DINT integers.
REAL These numbers use IEEE 754-1985 format to store numbers in following ranges. 32-bit single-precision floating point (REAL) – -3.40282E+38 to +3.40282E+38 64-bit double-precision floating point (LREAL) – -1.79769E+308 to +1.7976E+308 Floating Point refers to both REAL and LREAL data types.: Single precision floating point value - Real constant expressions must be valid number, and must include a dot ("."). If the user needs to enter a real expression having an integer value, add ".0" at the end of the number. The user can use "F" or "E" separators for specifying the exponent in case of a scientist representation. REAL is the default precision for floating points: such expressions do not need any prefix.
TIME: Time of day - Time constant expressions represent durations that must be less than 24 hours. Expressions must be prefixed by either "TIME#" or "T#". They are expressed as a number of hours followed by "h", a number of minutes followed by "m", a number of seconds followed by "s", and a number of milliseconds followed by "ms". The order of units (hour, minutes, seconds, milliseconds) must be respected. The user cannot insert blank characters in the time expression. There must be at least one valid unit letter in the expression.
String expressions must be written between single quote marks. The length of the string cannot exceed 255 characters. The user can use the following sequences to represent a special or not printable character within a string:
$$ | a "$" character |
$' | a single quote |
$T | a tab stop (ASCII ASCII - American Standard Code for Information Interchange - ASCII-coded characters are single-byte values in the range of 0 (zero) to 127. Codes in the range 128 to 255 are not defined by the ASCII standard, but rather by the equipment manufacturer. code 9) |
$R | a carriage return character (ASCII code 13) |
$L | a line feed character (ASCII code 10) |
$N | carriage return plus line feed characters (ASCII codes 13 and 10) |
$P | a page break character (ASCII code 12) |
$xx | any character (xx is the ASCII code expressed on two hexadecimal A base-16 numbering system which uses the symbols 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F for numeral. digits |
Constant Expression Examples
Below are some examples of valid constant expressions
TRUE |
TRUE Boolean expression |
FALSE |
FALSE Boolean expression |
SINT#127 |
small integer |
INT#2000 |
16 bit integer |
123456 |
DINT (32 bit) integer |
16#abcd |
DINT integer in hexadecimal basis |
0.0 |
0 expressed as a REAL number |
1.002E3 |
1002 expressed as a REAL number in scientist format |
T#23h59m59s999ms |
maximum TIME value |
TIME#0s |
null TIME value |
T#1h123ms |
TIME value with some units missing |
'hello' |
character string |
'name$Tage' |
character string with two words separated by a tab |
'I$'m here' |
character string with a quote inside (I'm here) |
'x$00y' |
character string with two characters separated by a null character (ASCII code 0) |
Below are some examples of typical errors in constant expressions
BooVar := | 0 and 1 cannot be used for Booleans |
1; | basis prefix ("16#") omitted |
1a2b | Time unit missing |
T#12 | quote within a string with "$" mark omitted |
'I'm here' hello |
quotes omitted around a character string |
Return to the Top: Program Variables in IEC
Variables Window in IEC
The IEC Program Variables window contains a list of the variables used in the IEC Programming section. To access the dockable Program Variables window via Home > View > Program Variables.
The columns of the Program Variables window can be made visible or invisible according to the requirement.
Double clicking on icon to bring up the following dialog. Here the individual columns can be made visible or invisible by checking or un-checking the individual check box. The width of each column and its position can also be set here.
Return to the Top: Program Variables in IEC
Declaring Variables in IEC
Attributes of a Variable in IEC
Each variable have an attribute displayed in the corresponding column of the grid. For each internal variable, user can select "Read Only". Otherwise, the "attribute" column of an internal variable is empty. Parameters of UDFBs are marked as either "IN" or "OUT". To change the attribute of an internal variable, enable the modification mode in theVariable - Active Grid and move the cursor to the selected "attribute" cell. Then press ENTER to set or reset the "Read Only" attribute.
Creating New Variables in IEC
-
Hit INSERT key in the Program Variables Window to create a new variable in the selected group. The variable is added at the end of the group. Variables are created with a default name. The user can rename a new variable or change its attribute using the variable editing grid.
-
In case of a group corresponding to local variables of a UDFB, pressing the INSERT key gives the user the choice between:
-
adding an "IN" (input) parameter
-
adding an "OUT" (output) parameter
-
adding a private variable
-
-
IN and OUT parameters always appear at the beginning of a UDFB group.
-
OUTPUT variables cannot be declared as arrays or structures, instead they can be declared as INOUT variables & used as outputs.
Defining Structures in IEC
To create a new type of data structure, right-click in the program variables window and select Add Structure. Each structure is represented as a group in the window. Enter the members of the structure in its group in the same way as variables are entered in another group. New data structures are created with default name. Use right-click option "Rename' to change its name. An instance of the structure can be created within another structure if the structure is already defined.
Initial Value of a Variable in IEC
A variable may have an initial value. The value must be a valid Constant Expressions that fits to the of the variable. The initial value is displayed in red if it is not a valid expression for the selected data type. There is no initial value for arrays and instances of function blocks. To change the initial value of a variable, enable the modification mode in the Variable - Active Grid and move the cursor to the selected "init value" cell. Then press ENTER to enter the new value.
Naming a Variable in IEC
To change the name of the variable, enable the modification mode in the Variable - Active Grid and move the cursor to the selected "name" cell. Then press ENTER or hit the first character of the new name. Name is entered in a small box. Hit ENTER to validate the name or ESCAPE to cancel the change. A variable must be identified by a unique name within its parent group. The variable name cannot be a reserved keyword of the programming languages and cannot have the same name as a standard or function block. A variable should not have the same name as a program or a user defined function block. The name of a variable should begin by a letter or an underscore ("_") mark, followed by letters, digits or underscore marks. It is not allowed to put two consecutive underscores within a variable name. Naming is case insensitive. Two names with different cases are considered as the same.
Sorting Variables in IEC
At any moment the user can sort variables of a group according to their name, type or dimension. For that the user simply needs to:
-
move the cursor to the header of the group
-
click on the name of the wished column
Cscape always keeps the original order of declared variables. Each time the user inserts a new variable or expand/collapse a group, the original sorting is re-applied.
Return to the Top: Program Variables in IEC
Mapping a Variable to an OCS Register in IEC
Cscape enables the user to freely enter for each variable two attributes that describe the variable:
-
The "Tag" is the address of the variable that can be displayed together with the variable name in graphic languages. The variable address is associated with the Memory Area of the OCS.
-
The "Description" is a long comment text that describes the variable.
To change the tag or description of a variable, enable the modification mode in theVariable - Active Grid and move the cursor to the corresponding cell. Then press ENTER to enter the new text.
How the IEC Compiler Maps Structures to OCS Registers
Mapping of structures to PLC registers when a structure is mapped occurs in two different ways dependent on whether ‘Arrays of Structures’ mode is in operation.
Return to the Top: Program Variables in IEC
'Arrays of Structures’ mode disabled in IEC
If ‘Arrays of Structures’ mode is not in use then all structures are "exploded" by the compiler as a set of individual variables, mixing %T Non-retentive single-bit registers. and %R Retentive 16-bit registers. memory locations. In this case, the structure has no real physical implementation when loaded to the OCS. You cannot override its location and you have no assurance that members (even ignoring BOOL members) are contiguous in memory. Attempts to map the structure by applying a register tag to the structure will cause a compiler warning to be generated.
‘Arrays of Structures’ mode enabled in IEC
All struct members are aligned according to the following rules:
-
Boolean data (BOOL Boolean- [Data Type BOOL] - A single bit, binary value, or register/variable. Boolean points have only two possible values, 'TRUE' or 'FALSE'.) is aligned on a byte offset
-
8 bit data (SINT Short Integer [Data Type SINT] - An 8-bit signed value. Short Integers are used where the value of the data is expected to be in the range of -128 to +127., USINT Unsigned Short Integer - [Data Type USINT] - An 8-bit unsigned value. Unsigned Short Integers are used where the value of the data is expected to be in the range of 0 (zero) to 255.) is aligned on an even byte offset
-
16 bit data (INT Integer - [Data Type INT] - A 16-bit signed value. Integers are used where the value of the data is expected to be in the range of -32,768 to +32,767., UINT Unsigned Integer - [Data Type UINT] - A 16-bit unsigned value. Unsigned Integers are used where the value of the data is expected to be in the range of -0 (zero) to 65,535.) is aligned on an even byte offset
-
32 bit data (DINT Double Integer - [Data Type DINT] - A 32-bit signed value. Double Integers are used where the value of the data is expected to be in the range of -2,147,483,648 to +2,147,483,647., UDINT Unsigned Double Integer - [Data Type UDINT] - A 32-bit unsigned value. Unsigned Double Integers are used where the value of the data is expected to be in the range of 0 (zero) to 4,294,967,296., TIME, REAL) is aligned on a byte offset multiple of 4
Structure in IEC Example
Fan_structure
Active (Boolean)
Status (Integer)
Online (Boolean)
RawAmps (Integer)
Byte offset in memory will be:
Byte Offset |
Structure Element |
Physical Element if mapped at R100 |
0 |
Active |
R100.0 |
2 |
Status |
R101 |
4 |
Online |
R102.0 |
6 |
RawAmps |
R103 |
We could pack this more efficiently by grouping any Booleans (and USINTs and SINTs) in the structure:
So for the example above we would define Fan_structure as
Fan_structure
Active (Boolean)
Online (Boolean)
Status (Integer)
Raw_amps (Integer)
This would give us byte offsets as follows:
Byte Offset |
Structure Element |
Physical Element if mapped at R100 |
0 |
Active |
R100.0 |
1 |
Online |
R100.8 |
2 |
Status |
R101 |
4 |
RawAmps |
R102 |
Note: Tags and structures are not supported by arrays of structure mode - this is a compiler limitation caused by the addressing mode used to access structures. This will be addressed in future.
Return to the Top: Program Variables in IEC
Variable Data Type and Dimension
To change the type and dimension of the variable, enable the modification mode in the Variable - Active Grid and move the cursor to the appropriate cell and press ENTER. Each variable must have a valid.It can be either a basic data type or a type of function block or UDFB. If the selected data type is STRING String - [Data Type STRING] - A variable-length succession of characters. Each character is represented by one byte. a. Cscape strings are delimited by the Single Quote character ('). b. Cscape strings may be zero characters in length., the user must specify a maximum length, and cannot exceed 255 characters.
Arrays: The user can specify dimension(s) for an internal variable, in order to declare an array. Arrays can be of 1, 2 or 3 dimensions & not more than that. All indexes are 0 based. For instance, in case of single dimension array, the first element is always identified by ArrayName[0]. The user cannot declare arrays of function block instances. The total number of items in an array (all dimensions together) cannot exceed 65535.
To use multidimensional array the syntax are as follows :
Single dimensional array - [x]
Two dimensional array - [x,y]
Three dimensional array - [x,y,z]
Using the Program Variables Window, the user must enter integer dimensions separated by commas. For instance:
3,10,5
Return to the Top: Program Variables in IEC
Variable - Active Grid
Hit SPACE bar to enable or disable the active grid. The Program Variables Window enables the user to enter information in each cell of the active grid. At any moment, the active grid can be activated (each cell can be edited independently) or disabled (full row is highlighted) by selecting the variable and pressing space. It can also be done through the 'Enable Changes' right-click option of the selected variable.
Press the ENTER key when the grid is inactive to open the variable setting box.
At any time the user can drag with the mouse column separators in the main grid header for resizing columns.
Press the following keys for browsing groups of variables:
-
Ctrl + Page Up - Move the selection to the head of the previous group
-
Ctrl + Page Down - Move the selection to the head of the following group
Return to the Top: Program Variables in IEC
Selecting Variables and Instances
Symbols of variables and instances are selected using the variable list, that can be used as the variable editor. Selecting variables is available from all editors:
-
In FBD diagrams, double click on a variable box, a FB instance name, a contact or a coil to select the associated variable.
-
In LD diagrams, double click on a contact, a coil or a block input or output to select the variable. Double click on the top of a FB rectangle to select an instance.
-
In ST/IL texts, place the cursor where variable needs to be inserted. Right-click and select Insert/Set Variable.
When the Program Variables Window is enabled from Home > View menu, the user can simply drag a variable from the list to the program to insert it.
If Editor Options > Diagrams > 'Prompt for Variable Name after insert' is checked, the Program Variables dialog gets opened when a variable is placed in the logic editing area.
Return to the Top: Program Variables in IEC
Editing Variables as Text
As an alternative to the user friendly grid for editing variables, it is possible to declare variables as text. Text editing applies to all the variables of a group. During text editing, the group and all its variables are locked in the grid so that no change can be entered from other windows.
Several syntax are available for describing variables:
IEC61131-3 Syntax |
The original IEC61131-3 syntax for declaring variables |
XML Tags |
An easy XML structure using tags and attributes |
CSV Format |
CSV format (separator: semicolon) |
To edit a group of variables as text, select the group in the program variables window. Right-click and select 'Edit Variables as text'. The Program Variables window goes blank and Logic editing area shows 3 tabs namely IEC format, XML format and CSV format. The user should select the appropriate tab in order to add variables. On pressing 'X' in the logic editing area, the user will be asked for saving. If the variables are saved, the same will be shown in Program Variables window. To edit a group of variable as text, select the corresponding tab ("IEC", "XML" or "CSV") at the bottom of the editing window, and then double click on the group name in the explorer pane.
Note:
-
Bit arrays must be tagged with registers.
-
The following ladder blocks must be tagged with registers - Multishift Bit, Multi rotate Bit, Modbus Slave, Modbus Master, Alarm Block and Indirect Move blocks.
-
For String Blocks (For example: String Move/String Compare), the configured maximum length size should be 2 bytes less than the array size.
-
Right-Clicking "Add to Data watch" will not add all the source and destination registers during Debug mode. To add all the registers in the buffer to the watch window add them before entering debug mode.
-
For data arrays, the user can give a range within the array that needs to be added in data watch. For example - src[0]-[10] etc.
-
Protocol dlls, Devicenet Scanner and J1939 modules do not support tag addressing. (All variables used in these modules should be fixed to physical address in the program variable window and the register references used in the appropriate configuration sections).
-
It is advised to configure variables/tags under Program Variables > Global Variables.
IEC61131-3 Syntax
Using IEC61131-3 syntax, variables are declared within structured blocks. Each blocks begins with "VAR", "VAR_INPUT", "VAR_OUTPUT" or "VAR_EXTERNAL" keyword and ending with "END_VAR" keyword (with no semicolon after). Below is the meaning of each keyword:
-
VAR: Memory variables. Can be global, local or RETAIN depending on the edited group
-
VAR_INPUT: Input parameters of a block. Available only when the edited group is a UDFB.
-
VAR_OUTPUT: Output parameters of a block. Available only when the edited group is a UDFB.
-
VAR_EXTERNAL: External variables. Can be global or local depending on the edited group
Basic syntax for declaring a variable
To declare a variable, simply enter its symbol, followed by ":" and its data type. If the data type is STRING, it must be followed the maximum length between parenthesis.
For example:
MyVar : BOOL;
MyString : STRING(255);
To indicate that a variable has the "read only" attribute, insert the "CONSTANT " keyword at the beginning of the variable declaration:
CONSTANT VarName : DataType;
To declare an array, the data type must be preceded by "ARRAY [ dimensions ] OF". There are at most 3 dimensions, separated by commas. Each dimension is specified as "0 .. MaxBound".
Below are examples:
Array1 : ARRAY [0 .. 99] OF DINT;
Matrix : ARRAY [0 .. 9, 0 .. 9, 0 .. 9] OF REAL;
Additionally, the user can specify an initial value for single variables. The initial value is entered after the data type, and is preceded by ":=". The initial value must be a valid constant expression that fits the data type.
Examples:
MyBool : BOOL := TRUE;
MyString : STRING(80) := 'Hello';
MyLongReal : LREAL := lreal#1.0E300;
Return to the Top: Program Variables in IEC
Additional information and description texts
As a variable may have additional properties and comment texts in Cscape, we use special directives entered as IEC comments AFTER the declaration of the variable, to specify additional info.
The following directives are available:
(*$tag=Text*) Variable tag (short comment)
(*$desc=Text*) Variable description
The user can also use "//" single line comments to enter the directives:
//$tag=Text
//$desc=Text
XML Tags
The user can describe variable using a simple XML structure, where each variable is described as an XML tag. The file must fit the basic XML syntax. Values of tag attributes must be entered between double quotes. Characters < > " ' & are reserved to XML and cannot appear in values of tag attributes.
Instead the user should use the following sequences:
< | < |
> | > |
" | " |
' | ' |
& | & |
Below is the tag structure for variable declaration:
(the "*" mark indicates that the tag can appear 0 or more times)
The rest of this page describes the format and meaning of each tag:
<k5project>
This tag must be entered at the top level and is unique. It is reserved for extensions (enhancement of the XML structure) and specifies the version of the syntax. Its attributes are:
Version | Reserved for future extensions. This attribute is mandatory and must be "1.0". |
The <K5Project> tag contains one <vargroup> tag.
<vargroup>
This tag must appear with the <K5Project> and contains all <var> tags for variables of the group. In this version, the tag has no attribute (the name of the group is implicit)
<var>
This tag describes the basic definition of one variable. Its attributes are:
name |
Symbol of the variable. This attribute is mandatory. |
type |
Name of the data type of the variable This attribute is mandatory |
len |
Maximum length if the data type is STRING. This attribute is mandatory for STRING variables, and should not appear for other data types |
dim |
Dimension(s) if the variable is an array. There are at most 3 dimensions, separated by commas. This attribute is optional. |
attr |
Attributes of the variable, separated by commas. Possible values are: IN : INPUT parameter (for UDFBs only) OUT : OUTPUT parameter (for UDFBs only) external : External variable constant : Variable is read only. This attribute is optional. |
init |
Initial value of the variable Must be a valid constant expression that fits the data type. This attribute is optional. |
The <var> tag contains zero or more <varinfo> tags.
<varinfo>
This tag indicates an additional info for the variable it belongs to. Its attributes are:
type |
Type of information contained in the "data" attribute. Possible values: tag : variable tag (short comment) desc : description This attribute is mandatory. |
data |
Data specified by the "type" attribute, in text format. This attribute is mandatory |
CSV Format
Using CSV format, each variable is defined on one line of text. Each component of the variable definition is entered as one CSV element. CSV elements are separated by semi-colons. Each element is written between double quotes. A double quote within an element is represented by two double quotes. CSV format is an easy way to exchange variable declaration with spreadsheet applications.
It is not mandatory that all elements (all columns) appear in the text. The first line must contain the list of columns used, using the following keywords:
name |
Symbol of the variable. This attribute is mandatory. |
type |
Name of the data type This item is mandatory, and must appear before len, dim and init columns. |
len |
String length if the data type is STRING. This item must be empty for other data types. |
dim | Dimension(s) if the variable is an array. There are at most 3 dimensions, separated by commas. |
attr |
Attributes of the variable, separated by commas. Possible values are: IN : INPUT parameter of a UDFB OUT : OUTPUT parameter of a UDFB external : external variable |
RO |
if "YES" indicates that the variable has the read-only attribute (Note: The user can also use "TRUE" or "1" value) |
init |
Initial value of the variable. Must be a valid constant expression that fits the data type. |
tag |
tag (short description text) |
desc |
description text |
Below is an example of CSV text for the declaration of 3 variables, with some columns missing:
"name","type","len","attr","RO"
"MyVar","BOOL","","","NO"
"ExtVar","DINT","","external","YES"
"MyStr","STRING","10","","NO"
Return to the Top: Program Variables in IEC