Object Property

Object Creating a property

Dialog Add property

Access modifier

In addition, a property can contain local variables. However, a property cannot contain additional inputs. In contrast to a function or method, it also cannot contain additional outputs.

If you copy or move a property from a POU to an interface, TwinCAT automatically deletes the included implementations.

Get and Set accessors

TwinCAT automatically adds the Get and Set accessor methods below the property object in the PLC project tree. The Add command can be used to add them explicitly.

TwinCAT calls the Set accessor when write access to the property occurs, i.e. when you use the property name as input parameter.

TwinCAT calls the Get accessor when read access to the property occurs, i.e. when you use the property name as output parameter.

Please note that you have to implement the accessor methods in order to access the property.

Implementation sample

Declaration of the function block FB_Sample

FUNCTION_BLOCK FB_Sample
VAR
    nVar : INT;
END_VAR

nVar := nVar + 1;

Declaration of the property nValue

PROPERTY PUBLIC nValue : INT

Implementation of the accessor method FB_Sample.nValue.Set

nVar := nValue;

Implementation of the accessor method FB_Sample.nValue.Get

nValue := nVar;

Calling the property nValue

PROGRAM MAIN
VAR
    fbSample : FB_Sample;
END_VAR

fbSample();
If fbSample.nValue > 500 THEN
    fbSample.nValue := 0;
END_IF;

If you only want to use the property for read access or only for write access, you can delete the unused accessor.

You can add access specifiers to the accessor methods in the following places: Through manual entries in the declaration part of the accessor. In the Add 'get' accessor or Add 'set' accessor dialog, when you add the accessor explicitly with the Add command.

Compatibility warning for properties of type REFERENCE In TC3.1 Build 4022 the calling behavior of properties defined with the return type 'REFERENCE TO <…>' changes. For write accesses using ':=', with versions < 3.1.4022.0 the set accessor is called so that the reference is written. With versions >= 3.1.4022.0, however, the get-accessor is called so that the value is written. To assign the reference with versions >= 3.1.4022.0, the reference assignment operator 'REF=' must be used.

Monitoring for properties in online mode

Pragmas are available for monitoring for properties in online mode, which should be added at the top of the definition property (Attribute 'monitoring'):

• {attribute 'monitoring':= 'variable'}: With each access to the property, TwinCAT stores the actual value in a variable and displays the value of this variable. This value may become obsolete, if the code no longer accesses the property.
• {attribute 'monitoring' := 'call'}: Each time the value is displayed, TwinCAT calls the code of the Get accessor. If this code contains a side effect, the side effect is executed by the monitoring.

You can monitor a property using the following features:

• Inline-Monitoring
  Requirement: In the TwinCAT options in the category TwinCAT > PLC Programming Environment > Text Editor the option Enable Inline-Monitoring is activated in the tab Monitoring .
• Watch List (Using Watchlists)

Access to a single element of a structured return type during method/function/property call

The following implementation can be used to directly access an individual element of the structured data type that is returned by the method/function/property when a method, function or property is called. A structured data type is, for example, a structure or a function block.

1. The return type of the method/function/property is defined as "REFERENCE TO <structured type>" (instead of just "<structured type>").
2. Note that with such a return type – if, for example, an FB-local instance of the structured data type is to be returned – the reference operator REF= must be used instead of the "normal" assignment operator :=.

The declarations and the sample in this section refer to the call of a property. However, they are equally transferrable to other calls that deliver return values (e.g. methods or functions).

Sample

Declaration of the structure ST_Sample (structured data type):

TYPE ST_Sample :
STRUCT
    bVar  : BOOL;
    nVar  : INT;
END_STRUCT
END_TYPE

Declaration of the function block FB_Sample:

FUNCTION_BLOCK FB_Sample
VAR
    stLocal     : ST_Sample;
END_VAR

Declaration of the property FB_Sample.MyProp with the return type "REFERENCE TO ST_Sample":

PROPERTY MyProp : REFERENCE TO ST_Sample

Implementation of the Get method of the property FB_Sample.MyProp:

MyProp REF= stLocal;

Implementation of the Set method of the property FB_Sample.MyProp:

stLocal := MyProp;

Calling the Get and Set methods in the main program MAIN:

PROGRAM MAIN
VAR
    fbSample    : FB_Sample;
    nSingleGet  : INT;
    stGet       : ST_Sample;    
    bSet        : BOOL;
    stSet       : ST_Sample;
END_VAR

// Get - single member and complete structure possible
nSingleGet := fbSample.MyProp.nVar;
stGet      := fbSample.MyProp;
 
// Set - only complete structure possible 
IF bSet THEN
    fbSample.MyProp REF= stSet;
    bSet            := FALSE;
END_IF 

Through the declaration of the return type of the property MyProp as "REFERENCE TO ST_Sample" and through the use of the reference operator REF= in the Get method of this property, a single element of the returned structured data type can be accessed directly on calling the property.

VAR
    fbSample    : FB_Sample;
    nSingleGet  : INT;
END_VAR

nSingleGet := fbSample.MyProp.nVar;

If the return type were only to be declared as "ST_Sample", the structure returned by the property would first have to be assigned to a local structure instance. The individual structure elements could then be queried on the basis of the local structure instance.

VAR
    fbSample    : FB_Sample; 
    stGet       : ST_Sample; 
    nSingleGet  : INT;
END_VAR

stGet      := fbSample.MyProp;
nSingleGet := stGet.nVar;

Access to VAR_IN_OUT variables of the function block in a method/transition/property

In principle, the VAR_IN_OUT variables of a function block can be accessed in a method, transition or property of the function block. Note the following for this type of access:

• If the body or an action of the function block is called from outside the FB, the compiler ensures that the VAR_IN_OUT variables of the function block are assigned with this call.
• This is not the case if a method, transition or property of the function block is called, since the VAR_IN_OUT variables of the FB cannot be assigned within a method, transition or property call. Therefore, access to the VAR_IN_OUT variables might occur by calling the method/transition/property before the VAR_IN_OUT variables are assigned to a valid reference. Since this would mean invalid access at runtime, accessing the VAR_IN_OUT variables of the FB in a method, transition or property is potentially risky.

Therefore, the following warning with ID C0371 is issued if the VAR_IN_OUT variables of the FB are accessed in a method, transition or property:

„Warning: Access to VAR_IN_OUT <Var> declared in <POU> from external context <Method/Transition/Property>”

An adequate response to this warning could be to check the VAR_IN_OUT variables within the method/transition/property before it is accessed. The operator __ISVALIDREF can be used for this check, to ascertain whether a reference refers to a valid value. If this check is enabled, it can be assumed that the user is aware of the risk that potentially exists when the VAR_IN_OUT variables of the FB are accessed in a method/transition/property. Checking the reference is regarded as adequate handling of this risk. The corresponding warning can therefore be suppressed via attribute 'warning disable'.

A sample implementation of a method is shown below.

Function block FB_Sample:

FUNCTION_BLOCK FB_Sample
VAR_IN_OUT
    bInOut : BOOL;
END_Var

Methode FB_Sample.MyMethod:

METHOD MyMethod
VAR_INPUT
END_VAR

// The warning can be disabled here as the user is aware of the risk that the reference may not be valid by checking its validity
{warning disable C0371}

// Checking the VAR_IN_OUT reference, leave the current method in case of invalid reference
IF NOT __ISVALIDREF(bInOut) THEN
     RETURN;
END_IF

// Access to VAR_IN_OUT reference (only if the reference was confirmed as valid before)
bInOut := NOT bInOut;

// The warning may be restored at the end of the access area
{warning restore C0371}

In the following sample, an input variable and a property are initialized by a function block that has an FB_init method with an additional parameter.

Function block FB_Sample:

FUNCTION_BLOCK FB_Sample
VAR_INPUT
    nInput           : INT;
END_VAR
VAR
    nLocalInitParam  : INT;
    nLocalProp       : INT;
END_VAR

Method FB_Sample.FB_init:

METHOD FB_init : BOOL
VAR_INPUT
    bInitRetains : BOOL;  // if TRUE, the retain variables are initialized (warm start / cold start)
    bInCopyCode  : BOOL;  // if TRUE, the instance afterwards gets moved into the copy code (online change)
    nInitParam   : INT;
END_VAR

nLocalInitParam := nInitParam;

Property FB_Sample.nMyProperty and the associated Set function:

PROPERTY nMyProperty : INT

nLocalProp := nMyProperty;

Program MAIN:

PROGRAM MAIN
VAR
    fbSample  : FB_Sample(nInitParam := 1) := (nInput := 2, nMyProperty := 3);
    aSample   : ARRAY[1..2] OF FB_Sample[(nInitParam := 4), (nInitParam := 7)]
                            := [(nInput := 5, nMyProperty := 6), (nInput := 8, nMyProperty := 9)];
END_VAR

Initialization result:

• fbSample
• nInput = 2
• nLocalInitParam = 1
• nLocalProp = 3
• aSample[1]
• nInput = 5
• nLocalInitParam = 4
• nLocalProp = 6
• aSample[2]
• nInput = 8
• nLocalInitParam = 7
• nLocalProp = 9