Program Variables in IEC

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

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.

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