Object Property

Symbol: Object Property 1:

A property is an extension of the IEC 61131-3 standard and is a means for object-oriented programming. It consists of the accessor methods Get and Set. TwinCAT automatically calls these methods when a read or write access occurs to the function block that implements the property.

Object Creating a property

1. Select a function block or a program in the Solution Explorer in the PLC project tree.
2. In the context menu select the command Add > Property...
The Add Property dialog opens.
3. Enter a name and select a return type, the implementation language, and optionally an access modifier.
4. Click on Open.
The object is added to the PLC project tree and opens in the editor.

Dialog Add property

Object Property 2:

Name

Name of the property

Return type

Type of the value that will be returned (default type or structured type)

Implementation language

Implementation language selection list

Access modifier

Access specifier

Regulates access to the data

  • PUBLIC: Access is not restricted (equivalent to specifying no access modifier).
  • PRIVATE: Access to the property is restricted to the function block or the program respectively.
  • PROTECTED: Access to the property is restricted to the program or the function block and its derivatives respectively.
  • INTERNAL: Access to the property is limited to the namespace (the library).

In addition to these access modifiers, you can manually add the FINAL modifier to a property:

FINAL: Overwriting the property in a derivative of the function block is not allowed. This means that the property may not be overwritten/extended in a possibly existing subclass.

Abstract

Object Property 3:: Indicates that the property has no implementation and that the implementation is provided by the derived FB.

Background information on the ABSTRACT keyword can be found under ABSTRACT concept.

Properties with a different access modifier than PUBLIC are marked with a signal symbol in the Solution Explorer in the PLC project tree.

Access modifier

Object icon

Signal symbol

PRIVATE

Object Property 4:

Object Property 5:(Lock)

PROTECTED

Object Property 6:

Object Property 7: (Star)

INTERNAL

Object Property 8:

Object Property 9: (Heart)

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.

Object Property 10:

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.

Object Property 11:

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.
Object Property 12:

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'):

You can monitor a property using the following features:

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:

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}

Initialization example:

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:

See also: