Reference Types

A reference type holds a pointer to a variable. References allow indirect access — reading or writing through the reference affects the original variable.

Note

This feature requires IEC 61131-3 Edition 3. Use --dialect iec61131-3-ed3 to enable it. See Enabling Dialects and Features for details.

Tip

References can also be enabled without full Edition 3 by passing --allow-ref-to, or by selecting a dialect that includes it. See Enabling Dialects and Features.

Note

Beckhoff TwinCAT and CODESYS spell references REFERENCE TO and bind them with the REF= operator (r REF= x;) rather than REF_TO and r := REF(x);. Enable this variant with --allow-reference-to, or a dialect that includes it. It describes the same underlying reference, but — unlike REF_TO — a REFERENCE TO variable auto-dereferences: a bare use reads through the reference and a bare := writes through it, with no ^ needed. Only the binding operator REF= and __ISVALIDREF(r) act on the reference itself:

r : REFERENCE TO INT;
r REF= counter;         (* bind the reference *)
value := r;             (* read through the reference (implicit deref) *)
r := 99;                (* write through the reference (implicit deref) *)
valid := __ISVALIDREF(r);  (* TRUE once bound, FALSE while unbound *)

Note

Beckhoff TwinCAT and CODESYS also have a pointer type, spelled POINTER TO and bound with the ADR() address-of operator. Enable it with --allow-pointer-to and --allow-adr, or a dialect that includes them. A POINTER TO variable behaves like REF_TO: reading or writing the target requires the explicit dereference operator ^, unlike the auto-dereferencing REFERENCE TO:

p : POINTER TO INT;
p := ADR(counter);      (* point at counter *)
value := p^;            (* read through the pointer *)
p^ := 99;               (* write through the pointer *)

IEC 61131-3

Section 2.3.3.1 (Edition 3)

Support

Supported (Edition 3)

Syntax

Declare a reference variable with REF_TO:

variable_name : REF_TO element_type

You can also create a named reference type:

TYPE
    IntRef : REF_TO INT;
END_TYPE

Operators

REF()

Creates a reference to a variable:

r := REF(counter);
^ (dereference)

Reads or writes the referenced variable:

value := r^;    (* read through reference *)
r^ := 99;       (* write through reference *)
NULL

A literal representing an empty reference. Can be assigned to any REF_TO variable and compared with = or <>:

r := NULL;
IF r <> NULL THEN
    value := r^;
END_IF;

Example

PROGRAM main
  VAR
    counter : INT := 42;
    r : REF_TO INT := REF(counter);
    value : INT;
  END_VAR

  (* Read through the reference *)
  value := r^;

  (* Write through the reference — changes counter *)
  r^ := 99;
END_PROGRAM

Restrictions

  • REF() accepts only simple named variables (not array elements or literals).

  • References to temporary variables (VAR_TEMP, function parameters) are not allowed.

  • Nested references (REF_TO REF_TO) are not supported.

  • Arithmetic on references is not supported by default. Use --allow-ref-arithmetic to enable it.

  • Only = and <> comparison operators work with references by default. Use --allow-ref-arithmetic to enable ordering comparisons.

External References

See Also