329

19. STRUCTURED TEXT PROGRAMMING

Topics:
Basic language structure and syntax
Variables, functions, values
Program flow commands and structures
Function names
Program Example
Objectives:
To be able to write functions in Structured Text programs
To understand the parallels between Ladder Logic and Structured Text
To understand differences between Allen Bradley and the standard

19.1 INTRODUCTION
If you know how to program in any high level language, such as Basic or C, you will be comfortable with Structured Text (ST) programming. ST programming is part of the IEC 61131 standard.
An example program is shown in Figure 261. The program is called main and is defined between the
statements PROGRAM and END_PROGRAM. Every program begins with statements the define the
variables. In this case the variable i is defined to be an integer. The program follows the variable declarations. This program counts from 0 to 10 with a loop. When the example program starts the value of
integer memory i will be set to zero. The REPEAT and END_REPEAT statements define the loop. The
UNTIL statement defines when the loop must end. A line is present to increment the value of i for each
loop.

PROGRAM main
VAR
i : INT;
END_VAR
i := 0;
REPEAT
i := i + 1;
UNTIL i >= 10;
END_REPEAT;
END_PROGRAM
Figure 261

Note: Allen Bradley does not implement

the standard so that the programs can be
written with text only. When programming in RSLogix, only the section indicated to the left would be entered. The
variable i would be defined as a tag,
and the program would be defined as a
task.

A Structured Text Example Program

One important difference between ST and traditional programming languages is the nature of

330

program flow control. A ST program will be run from beginning to end many times each second. A traditional program should not reach the end until it is completely finished. In the previous example the
loop could lead to a program that (with some modification) might go into an infinite loop. If this were
to happen during a control application the controller would stop responding, the process might become
dangerous, and the controller watchdog timer would force a fault.
ST has been designed to work with the other PLC programming languages. For example, a ladder logic program can call a structured text subroutine.

19.2 THE LANGUAGE

The language is composed of written statements separated by semicolons. The statements use
predefined statements and program subroutines to change variables. The variables can be explicitly
defined values, internally stored variables, or inputs and outputs. Spaces can be used to separate statements and variables, although they are not often necessary. Structured text is not case sensitive, but it
can be useful to make variables lower case, and make statements upper case. Indenting and comments
should also be used to increase readability and documents the program. Consider the example shown in
Figure 262.

FUNCTION sample
INPUT_VAR

GOOD

start : BOOL; (* a NO start input *)

stop : BOOL; (* a NC stop input *)
END_VAR
OUTPUT_VAR
motor : BOOL;(* a motor control relay
*)
END_VAR
motor := (motor + start) * stop;(* get the motor output *)
END_FUNCTION

BAD

Figure 262

FUNCTION sample
INPUT_VAR
START:BOOL;STOP:BOOL;
END_VAR
OUTPUT_VAR
MOTOR:BOOL;
END_VAR
MOTOR:=(MOTOR+START)*STOP;END_FUNCTION
A Syntax and Structured Programming Example

331

19.2.1 Elements of the Language

ST programs allow named variables to be defined. This is similar to the use of symbols when
programming in ladder logic. When selecting variable names they must begin with a letter, but after
that they can include combinations of letters, numbers, and some symbols such as _. Variable names
are not case sensitive and can include any combination of upper and lower case letters. Variable names
must also be the same as other key words in the system as shown in Figure 263. In addition, these variable must not have the same name as predefined functions, or user defined functions.

Invalid variable names: START, DATA, PROJECT, SFC, SFC2, LADDER, I/O, ASCII,
CAR, FORCE, PLC2, CONFIG, INC, ALL, YES, NO, STRUCTURED TEXT
Valid memory/variable name examples: TESTER, I, I:000, I:000/00, T4:0, T4:0/DN,
T4:0.ACC
Figure 263

Acceptable Variable Names

When defining variables one of the declarations in Figure 264 can be used. These define the
scope of the variables. The VAR_INPUT, VAR_OUTPUT and VAR_IN_OUT declarations are used for
variables that are passed as arguments to the program or function. The RETAIN declaration is used to
retain a variable value, even when the PLC power has been cycled. This is similar to a latch application.
As mentioned before these are not used when writing Allen Bradley programs, but they are used when
defining tags to be used by the structured programs.

Declaration

Description

VAR
VAR_INPUT
VAR_OUTPUT
VAR_IN_OUT
VAR_EXTERNAL
VAR_GLOBAL
VAR_ACCESS
RETAIN
CONSTANT
AT

the general variable declaration

defines a variable list for a function
defines output variables from a function
defines variable that are both inputs and outputs from a function

END_VAR
Figure 264

a global variable
a value will be retained when the power is cycled
a value that cannot be changed
can tie a variable to a specific location in memory (without this variable locations are chosen by the compiler
marks the end of a variable declaration

Variable Declarations

Examples of variable declarations are given in Figure 265.

332

Text Program Line

Description

VAR AT %B3:0 : WORD; END_VAR

VAR AT %N7:0 : INT; END_VAR
VAR RETAIN AT %O:000 : WORD ; END_VAR
VAR_GLOBAL A AT %I:000/00 : BOOL ; END_VAR
VAR_GLOBAL A AT %N7:0 : INT ; END_VAR
VAR A AT %F8:0 : ARRAY [0..14] OF REAL; END_VAR
VAR A : BOOL; END_VAR
VAR A, B, C : INT ; END_VAR
VAR A : STRING[10] ; END_VAR
VAR A : ARRAY[1..5,1..6,1..7] OF INT; END_VAR
VAR RETAIN RTBT A : ARRAY[1..5,1..6] OF INT;
END_VAR
VAR A : B; END_VAR
VAR CONSTANT A : REAL := 5.12345 ; END_VAR
VAR A AT %N7:0 : INT := 55; END_VAR
VAR A : ARRAY[1..5] OF INT := [5(3)]; END_VAR
VAR A : STRING[10] := test; END_VAR
VAR A : ARRAY[0..2] OF BOOL := [1,0,1]; END_VAR
VAR A : ARRAY[0..1,1..5] OF INT := [5(1),5(2)];
END_VAR

a word in bit memory

an integer in integer memory
makes output bits retentive
variable A as input bit
variable A as an integer
an array A of 15 real values
a boolean variable A
integers variables A, B, C
a string A of length 10
a 5x6x7 array A of integers
a 5x6 array of integers, filled
with zeros after power off
A is data type B
a constant value A
A starts with 55
A starts with 3 in all 5 spots
A contains test initially
an array of bits
an array of integers filled with 1
for [0,x] and 2 for [1,x]

Figure 265

Variable Declaration Examples

Basic numbers are shown in Figure 266. Note the underline _ can be ignored, it can be used to
break up long numbers, ie. 10_000 = 10000. These are the literal values discussed for Ladder Logic.

number type

examples

integers
real numbers
real with exponents
binary numbers
octal numbers
hexadecimal numbers
boolean

-100, 0, 100, 10_000

-100.0, 0.0, 100.0, 10_000.0
-1.0E-2, -1.0e-2, 0.0e0, 1.0E2
2#111111111, 2#1111_1111, 2#1111_1101_0110_0101
8#123, 8#777, 8#14
16#FF, 16#ff, 16#9a, 16#01
0, FALSE, 1, TRUE

Figure 266

Literal Number Examples

Character strings defined as shown in Figure 267.

333

example

description

, a, $, $$

a zero length string

a single character, a space, or a, or a single quote, or a dollar
sign $
produces ASCII CR, LF combination - end of line characters
form feed, will go to the top of the next page
tab
a string that results in this<TAB>is a test<NEXT LINE>

$R$L, $r$l,$0D$0A
$P, $p
$T, 4t
this%Tis a test$R$L
Figure 267

Character String Data

Basic time and date values are described in Figure 268 and Figure 269. Although it should be
noted that for ControlLogix the GSV function is used to get the values.

Time Value

Examples

25ms
5.5hours
3days, 5hours, 6min, 36sec

T#25ms, T#25.0ms, TIME#25.0ms, T#-25ms, t#25ms

TIME#5.3h, T#5.3h, T#5h_30m, T#5h30m
TIME#3d5h6m36s, T#3d_5h_6m_36s

Figure 268

Time Duration Examples

description

examples

date values
time of day
date and time

DATE#1996-12-25, D#1996-12-25
TIME_OF_DAY#12:42:50.92, TOD#12:42:50.92
DATE_AND_TIME#1996-12-25-12:42:50.92, DT#1996-12-25-12:42:50.92

Figure 269

Time and Date Examples

The math functions available for structured text programs are listed in Figure 270. It is worth
noting that these functions match the structure of those available for ladder logic. Other, more
advanced, functions are also available - a general rule of thumb is if a function is available in one language, it is often available for others.

334

:=
+
/
*
MOD(A,B)
SQR(A)
FRD(A)
TOD(A)
NEG(A)
LN(A)
LOG(A)
DEG(A)
RAD(A)
SIN(A)
COS(A)
TAN(A)
ASN(A)
ACS(A)
ATN(A)
XPY(A,B)
A**B
Figure 270

assigns a value to a variable

addition
subtraction
division
multiplication
modulo - this provides the remainder for an integer divide A/B
square root of A
from BCD to decimal
to BCD from decimal
reverse sign +/natural logarithm
base 10 logarithm
from radians to degrees
to radians from degrees
sine
cosine
tangent
arcsine, inverse sine
arccosine - inverse cosine
arctan - inverse tangent
A to the power of B
A to the power of B
Math Functions

Functions for logical comparison are given in Figure 271. These will be used in expressions
such as IF-THEN statements.

>
>=
=
<=
<
<>
Figure 271

greater than
greater than or equal
equal
less than or equal
less than
not equal
Comparisons

Boolean algebra functions are available, as shown in Figure 272. The can be applied to bits or
integers.

335

AND(A,B)
OR(A,B)
XOR(A,B)
NOT(A)
!
Figure 272

logical and
logical or
exclusive or
logical not
logical not (note: not implemented on AB controllers)
Boolean Functions

highest priority

The precedence of operations are listed in Figure 273 from highest to lowest. As normal expressions that are the most deeply nested between brackets will be solved first. (Note: when in doubt use
brackets to ensure you get the sequence you expect.)

! - (Note: not available on AB controllers)

()
functions
XPY, **
negation
SQR, TOD, FRD, NOT, NEG, LN, LOG, DEG, RAD, SIN, COS, TAN, ASN, ACS, ATN
*, /, MOD
+, >, >=, =, <=, <, <>
AND (for word)
XOR (for word)
OR (for word)
AND (bit)
XOR (bit)
OR (bit)
ladder instructions
Figure 273

Operator Precedence

Common language structures include those listed in Figure 274.

IF-THEN-ELSIF-ELSE-END_IF;
CASE-value:-ELSE-END_CASE;
FOR-TO-BY-DO-END_FOR;
WHILE-DO-END_WHILE;
Figure 274

normal if-then structure

a case switching function
for-next loop

Flow Control Functions

Special instructions include those shown in Figure 275.

336

RETAIN();
IIN();
EXIT;
EMPTY
Figure 275

causes a bit to be retentive

immediate input update
will quit a FOR or WHILE loop

Special Instructions

19.2.2 Putting Things Together in a Program

Consider the program in Figure 276 to find the average of five values in a real array f[]. The
FOR loop in the example will loop five times adding the array values. After that the sum is divided to
get the average.

avg := 0;
FOR (i := 0 TO 4) DO
avg := avg + f[i];
END_FOR;
avg := avg / 5;
Figure 276

A Program To Average Five Values In Memory With A For-Loop

The previous example is implemented with a WHILE loop in Figure 277. The main differences
is that the initial value and update for i must be done manually.

avg := 0;
i := 0;
WHILE (i < 5) DO
avg := avg + f[i];
i := i + 1;
END_WHILE;
avg := avg / 5;
Figure 277

A Program To Average Five Values In Memory With A While-Loop

The example in Figure 278 shows the use of an IF statement. The example begins with a timer.
These are handled slightly differently in ST programs. In this case if b is true the timer will be active,
if it is false the timer will reset. The second instruction calls TONR to update the timer. (Note: ST programs use the FBD_TIMER type, instead of the TIMER type.) The IF statement works as normal, only
one of the three cases will occur with the ELSE defining the default if the other two fail.

337

t.TimerEnable := b;
TONR(t);
IF (a = 1) THEN
x := 1;
ELSIF (b = 1 AND t.DN = 1) THEN
y := 1;
IF (I:000/02 = 0) THEN
z := 1;
END_IF;
ELSE
x := 0;
y := 0;
z := 0;
END_IF;
Figure 278

Example With An If Statement

Figure 279 shows the use of a CASE statement to set bits 0 to 3 of a based upon the value of
test. In the event none of the values are matched, a will be set to zero, turning off all bits.

CASE test OF
0:
a.0 := 1;
1:
a.1 := 1;
2:
a.2 := 1;
3:
a.3 := 1;
ELSE
a := 0;
END_CASE;
Figure 279

Use of a Case Statement

The example in Figure 280 accepts a BCD input from bcd_input and uses it to change the
delay time for TON delay time. When the input test_input is true the time will count. When the timer
is done set will become true.

338

FRD (bcd_input, delay_time);

t.PRE := delay_time;
IF (test_input) THEN
t.EnableTimer := 1;
ELSE
t.EnableTimer := 0;
END_IF;
TONR(t);
set := t.DN;
Figure 280

Function Data Conversions

Most of the IEC61131-3 defined functions with arguments are given in Figure 281. Some of the
functions can be overloaded, for example ADD could have more than two values to add, and others
have optional arguments. In most cases the optional arguments are things like preset values for timers.
When arguments are left out they default to values, typically 0. ControlLogix uses many of the standard
function names and arguments but does not support the overloading part of the standard.

339

Function

Description

ABS(A);
ACOS(A);
ADD(A,B,...);
AND(A,B,...);
ASIN(A);
ATAN(A);
BCD_TO_INT(A);
CONCAT(A,B,...);
COS(A);
CTD(CD:=A,LD:=B,PV:=C);
CTU(CU:=A,R:=B,PV:=C);
CTUD(CU:=A,CD:=B,R:=C,LD:
=D,PV:=E);
DELETE(IN:=A,L:=B,P:=C);
DIV(A,B);
EQ(A,B,C,...);
EXP(A);
EXPT(A,B);
FIND(IN1:=A,IN2:=B);
F_TRIG(A);
GE(A,B,C,...);
GT(A,B,C,...);
INSERT(IN1:=A,IN2:=B,P:=C);
INT_TO_BCD(A);
INT_TO_REAL(A);
LE(A,B,C,...);
LEFT(IN:=A,L:=B);
LEN(A);
LIMIT(MN:=A,IN:=B,MX:=C);
LN(A);
LOG(A);
LT(A,B,C,...);
MAX(A,B,...);
MID(IN:=A,L:=B,P:=C);
MIN(A,B,...);
MOD(A,B);
MOVE(A);
MUL(A,B,...);
MUX(A,B,C,...);
NE(A,B);
NOT(A);
OR(A,B,...);

absolute value of A
the inverse cosine of A
add A+B+...
logical and of inputs A,B,...
the inverse sine of A
the inverse tangent of A
converts a BCD to an integer
will return strings A,B,... joined together
finds the cosine of A
down counter active <=0, A decreases, B loads preset
up counter active >=C, A decreases, B resets
up/down counter combined functions of the up and
down counters
will delete B characters at position C in string A
A/B
will compare A=B=C=...
finds e**A where e is the natural number
A**B
will find the start of string B in string A
a falling edge trigger
will compare A>=B, B>=C, C>=...
will compare A>B, B>C, C>...
will insert string B into A at position C
converts an integer to BCD
converts A from integer to real
will compare A<=B, B<=C, C<=...
will return the left B characters of string A
will return the length of string A
checks to see if B>=A and B<=C
natural log of A
base 10 log of A
will compare A<B, B<C, C<...
outputs the maximum of A,B,...
will return B characters starting at C of string A
outputs the minimum of A,B,...
the remainder or fractional part of A/B
outputs the input, the same as :=
multiply values A*B*....
the value of A will select output B,C,...
will compare A <> B
logical not of A
logical or of inputs A,B,...

340

Function

Description

REAL_TO_INT(A);
REPLACE(IN1:=A,IN2:=B,L:=
C,P:=D);
RIGHT(IN:=A,L:=B);
ROL(IN:=A,N:=B);
ROR(IN:=A,N:=B);
RS(A,B);
RTC(IN:=A,PDT:=B);
R_TRIG(A);
SEL(A,B,C);
SHL(IN:=A,N:=B);
SHR(IN:=A,N:=B);
SIN(A);
SQRT(A);
SR(S1:=A,R:=B);
SUB(A,B);
TAN(A);
TOF(IN:=A,PT:=B);
TON(IN:=A,PT:=B);
TP(IN:=A,PT:=B);
TRUNC(A);
XOR(A,B,...);

converts A from real to integer

will replace C characters at position D in string A with
string B
will return the right A characters of string B
rolls left value A of length B bits
rolls right value A of length B bits
RS flip flop with input A and B
will set and/or return current system time
a rising edge trigger
if a=0 output B if A=1 output C
shift left value A of length B bits
shift right value A of length B bits
finds the sine of A
square root of A
SR flipflop with inputs A and B
A-B
finds the tangent of A
off delay timer
on delay timer
pulse timer - a rising edge fires a fixed period pulse
converts a real to an integer, no rounding
logical exclusive or of inputs A,B,...

Figure 281

Structured Text Functions

Control programs can become very large. When written in a single program these become confusing, and hard to write/debug. The best way to avoid the endless main program is to use subroutines
to divide the main program. The IEC61131 standard allows the definition of subroutines/functions as
shown in Figure 282. The function will accept up to three inputs and perform a simple calculation. It
then returns one value. As mentioned before ControlLogix does not support overloading, so the function would not be able to have a variable size argument list.

....
D := TEST(1.3, 3.4); (* sample calling program, here C will default to 3.14 *)
E := TEST(1.3, 3.4, 6.28); (* here C will be given a new value *)
....
FUNCTION TEST : REAL
VAR_INPUT A, B : REAL; C : REAL := 3.14159; END VAR
TEST := (A + B) / C;
END_FUNCTION
Figure 282

Declaration of a Function

341

19.3 AN EXAMPLE
The example beginning in Figure 284 shows a subroutine implementing traffic lights in ST for
the ControlLogix processor. The variable state is used to keep track of the current state of the lights.
Timer enable bits are used to determine which transition should be checked. Finally the value of state
is used to set the outputs. (Note: this is possible because = and := are not the same.) This subroutine
would be stored under a name such as TrafficLights. It would then be called from the main program as
shown in Figure 283.

JSR
Function Name: TrafficLights

Figure 283

The Main Traffic Light Program

342

SBR();
IF S:FS THEN
state := 0;
green_EW.TimerEnable := 1;
yellow_EW.TimerEnable := 0;
green_NS.TimerEnable := 0;
yellow_NS.TimerEnable := 0;
END_IF;
TONR(green_EW); TONR(yellow_EW);
TONR(green_NS); TONR(yellow_NS);
CASE state OF
0:
IF green_EW.DN THEN
state :=1;
green_EW.TimerEnable := 0;
yellow_EW.TimerEnable := 1;
END_IF
1:
IF yellow_EW.DN THEN
state :=2;
yellow_EW.TimerEnable := 0;
green_NS.TimerEnable := 1;
END_IF
2:
IF green_NS.DN THEN
state :=3;
green_NS.TimerEnable := 0;
yellow_NS.TimerEnable := 1;
END_IF
3:
IF yellow_NS.DN THEN
state :=0;
yellow_NS.TimerEnable := 0;
green_EW.TimerEnable := 1;
END_IF
light_EW_green := (state = 0);
light_EW_yellow := (state = 1);
light_EW_red := (state = 2) OR (state = 3);
light_NS_green := (state = 2);
light_NS_yellow := (state = 3);
light_NS_red := (state = 0) OR (state = 1);
RET();
Figure 284

Traffic Light Subroutine

Note: This example is for the AB

ControlLogix platform, so it
does not show the normal
function and tag definitions.
These are done separately in
the tag editor.
state : DINT
green_EW : FBD_TIMER
yellow_EW : FBD_TIMER
green_NS : FBD_TIMER
yellow_NS : FBD_TIMER
light_EW_green : BOOL alias =
rack:1:O.Data.0
light_EW_yellow : BOOL alias =
rack:1:O.Data.1
light_EW_red : BOOL alias =
rack:1:O.Data.2
light_NS_green : BOOL alias =
rack:1:O.Data.3
light_NS_yellow : BOOL alias =
rack:1:O.Data.4
light_NS_red : BOOL alias =
rack:1:O.Data.5

343

19.4 SUMMARY
Structured text programming variables, functions, syntax were discussed.
The differences between the standard and the Allen Bradley implementation were indicated as
appropriate.
A traffic light example was used to illustrate a ControlLogix application

19.5 PRACTICE PROBLEMS

1. Write a structured text program that will replace the following ladder logic.
A

active

EQU
Source A 20
Source B n

MOV
Source -2
Dest n

LEQ
Source A n
Source B 20

active

active
active
ADD
Source A n
Source B 2
Dest n
LOG
Source n
Dest x
SUB
Source A x
Source B 1
Dest x
MUL
Source A x
Source B 2
Dest x
2. Implement the following Boolean equations in a Structured Text program. If the program was for a state
machine what changes would be required to make it work?
light = ( light + dark switch ) switch light
dark = ( dark + light switch ) switch dark

344

3. Convert the following state diagram to a Structured Text program.

C
FS

Y
D

4. A temperature value is stored in F8:0. When it rises above 40 the following sequence should occur once.
Write a ladder logic program that implement this function with a Structured Text program.
horn
2

11

15

t (s)

5. Write a structured text program that will replace the following ladder logic.
A

active

EQU
Source A 20
Source B n

MOV
Source -2
Dest n

LEQ
Source A n
Source B 20

active

active
active
ADD
Source A n
Source B 2
Dest n
LOG
Source n
Dest x
SUB
Source A x
Source B 1
Dest x
MUL
Source A x
Source B 2
Dest x

345

19.6 ASSIGNMENT PROBLEMS

1. Write logic for a traffic light controller using structured text.
2. Write a structured text program to control a press that has an advance and retract with limit switches. The
press is started and stopped with start and stop buttons.
3. Write a structured text program to sort a set of ten integer numbers and then find the median value.

346