What are the semantics of input variables passed by reference?

Question

Beckhoff's TwinCat-3, as well as Codesys 3 it's based on, adds references as an extension to IEC-61131-3 languages. I'm wondering what is the exact grammar and semantics of this non-standard addition (that's the problem with them: nobody bothers documenting them as well as a standard would).

It the following F_IsNonEmpty function valid and doing what one would expect, when invoked from the F_Test test function below?

FUNCTION F_IsNonEmpty : BOOL
  VAR_INPUT
    text : REFERENCE TO STRING;
  END_VAR
  F_IsNonEmpty := LEN(text) > 0;
END_FUNCTION

FUNCTION F_Test1
  VAR
    testMessage : STRING := '123';
  END_VAR
  IF F_IsNonEmpty(text := testMessage) THEN
    {...}
  END_IF
END_FUNCTION

Given that the target of the reference must be initialized using the REF= operator (v.s. e.g. C++ where reference targets are immutable), I'd have expected that the following invoking code would be correct instead - but it doesn't even compile:

FUNCTION F_Test2
  VAR
    testMessage : STRING := '123';
  END_VAR
  IF F_IsNonEmpty(text REF= testMessage) THEN
    {...}
  END_IF
END_FUNCTION

It seems that F_Test1 works correctly, but I'd like someone who actually uses Codesys 3 or TwinCat-3 REFERENCE TO feature to confirm.

Answer 1

When you use a REFERENCE in a VAR_INPUT, it's as if you were using a VAR_IN_OUT variable. Otherwise if you declare your REFERENCE in the VAR section, you need to use REF= when assigning another variable to it (or get an exception).

In essence, REFERENCE (like a VAR_IN_OUT var) is a more convenient and "safe" pointer because the dereference operator ^ is not needed and because the type is checked at compile time.