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

Nested references

A reference can refer to a reference variable. REF_TO REF_TO INT is a reference to a REF_TO INT, REF(r) of a reference variable r is one, and each ^ follows one level:

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

  value := rr^^;     (* the INT r refers to: 42 *)
  rr^^ := 99;        (* writes counter *)
  rr^ := REF(other); (* r now refers to other *)
END_PROGRAM

A reference to a reference is checked at each level: rr^ is a REF_TO INT and takes only REF(), NULL or another reference to an INT, and rr^^ is the INT. Storing a reference to a reference where a reference to a value is expected, as r := REF(r) does, is P2032. The TwinCAT REFERENCE TO does not nest, as in TwinCAT: see P2036.

Restrictions

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

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

  • An array, a structure or a string reached through a reference to a reference (rr^^[i]) is not supported yet.

  • 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