Object Property - Beckhoff Information System - English

Object Property

Symbol:

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

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

: 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		(Lock)
PROTECTED		(Star)
INTERNAL		(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.

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_SampleVAR    nVar : INT;END_VARnVar := 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 MAINVAR    fbSample : FB_Sample;END_VARfbSample();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-MonitoringRequirement: 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_STRUCTEND_TYPE

Declaration of the function block FB_Sample:

FUNCTION_BLOCK FB_SampleVAR    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 MAINVAR    fbSample    : FB_Sample;    nSingleGet  : INT;    stGet       : ST_Sample;     bSet        : BOOL;    stSet       : ST_Sample;END_VAR// Get - single member and complete structure possiblenSingleGet := 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_VARnSingleGet := 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_VARstGet      := 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_SampleVAR_IN_OUT    bInOut : BOOL;END_Var

Methode FB_Sample.MyMethod:

METHOD MyMethodVAR_INPUTEND_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 referenceIF 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_SampleVAR_INPUT    nInput           : INT;END_VARVAR    nLocalInitParam  : INT;    nLocalProp       : INT;END_VAR

Method FB_Sample.FB_init:

METHOD FB_init : BOOLVAR_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_VARnLocalInitParam := nInitParam;

Property FB_Sample.nMyProperty and the associated Set function:

PROPERTY nMyProperty : INTnLocalProp := nMyProperty;

Program MAIN:

PROGRAM MAINVAR    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

See also:

• Object Interface property
• Object-oriented programming
• Extending a function block
• Reference programming > Methods FB_init, FB_reinit and FB_exit