Object ‘Symbol Configuration’

You can use the symbol configuration for creating symbol descriptions for project variables. Click Project ‣ Add Object to add a symbol configuration object to the device tree. Then define specific presets. See dialog below: Add Symbol Configuration.

Double-click the Symbol Configuration object to open the symbol configuration editor.

Dialog ‘Add Symbol Configuration’

Function: This dialog is used to define the defaults for a Symbol Configuration object.

Call: Project ‣ Add Object ‣ Symbol Configuration menu; context menu of the application object.

Include comments in XML

Exports the symbol file with the comments assigned to the variables.

Support OPC UA features

Note: Availability and editability of this option depend on the device.

: When downloading the symbol configuration, additional information is also downloaded to the controller. The information below is necessary for operating the OPC UA server.

  • Base types of inherited function blocks

  • Contents of attributes that were assigned via compiler pragmas

  • Scopes (example: VAR_INPUT, VAR_OUTPUT, VAR_IN_OUT)
Client-Side Data Layout

For detailed information and examples of layout options, see the next section “Symbol Configuration Editor”.

Compatibility layout

This setting is used for the compatibility of old projects. The data layout created for the client is matched as much as possible to the layout created internally by the compiler.

Optimized layout

Recommended for new projects. Calculates the output layout in optimized form detached from the internal compiler layout. Does not generate any gaps for unpublished elements and strictly fulfills the requirements for memory alignment of the data types. Requires compiler version 3.5.7.0 or higher.

Symbol configuration editor

The editor includes a table with selected variables and a menu bar for editing.

Menu bar

View

You can use this button for activating and deactivating the following categories of variables used in the configuration editor:

  • Unconfigured from Project: Variables that have not been added to the symbol configuration, but are provided in the project.

  • Unconfigured from Libraries: Variables that have not been added to the symbol configuration, but are provided in the project.

  • Symbols Exported via Attribute: This filter also lists the variables that have already been marked for export in the symbol file by means of the {attribute 'symbol' := 'read'} pragma. These symbols are displayed in gray. The Attribute column shows which access rights are set by the pragma.

Build

Compiles the project. Requirement for current preparation of variables in the configuration editor.

Settings

  • Support OPC UA features:

    Note: Availability and editability of this option depend on the device.

    : When downloading the symbol configuration, additional information is also downloaded to the controller. The information below is necessary for operating the OPC UA server. This currently includes the following information:

    • Base types of inherited function blocks

    • Contents of attributes that were assigned via compiler pragmas

    • Scopes (example: VAR_INPUT, VAR_OUTPUT, VAR_IN_OUT)

  • <!> Include comments in XML

    : Exports the symbol file with the comments assigned to the variables.

  • Include Node Flags in XML

    : The namespace node flags provide additional information about the origin of a node in the namespace. The node flags always in the symbol table when OPC UA is activated. However, its inclusion in the XML file can be deactivated as some defective parsers have problems with it.

  • Configure Comments and Attributes

    Opens the Comments and Attributes dialog. Here you configure the details of what should be included in the symbol configuration and XML file with respect to comments and attributes.

  • Configure synchronization with IEC tasks:

    Opens the Properties - <device name> dialog, Options tab.

    This setting allows for the symbolic clients (e.g. visualizations or database links based on the PLCHandler) to have consistent read/write access synchronized with the IEC tasks. For a detailed description of this setting, see the “Setting: Configure synchronization with IEC tasks” section below.

    Note: Variable access which is synchronous with the IEC tasks can increase the jitter for all IEC applications on this device. Synchronized consistent access can interrupt the real-time capability.

  • List box for defining the data layout type for the client of the symbol configuration:

    Note: See the “Example of data layout types” section at the end of this help page.

    • Optimized layout: Recommend for new projects. Calculates the output layout in optimized form detached from the internal compiler layout. Does not generate any gaps for unpublished elements and strictly fulfills the requirements for memory alignment of the data types. Requires compiler version 3.5.7.0 or higher.

    • Compatibility layout: This setting is used for the compatibility of old projects. The data layout created for the client is matched as much as possible to the layout created internally by the compiler.

      Due to the configuration possibilities of the symbol configuration which have grown over time, problematic offsets can still result.

      Causes of offsets

      Memory gaps due to internal pointers or references in function blocks and structure components that are not released for symbol configuration.

      Memory gaps that occur differently in 32-bit and 64-bit systems depending on the data type, such as __XINT / __XWORD .

      Fields that are at uneven addresses. Some clients are not set up for this.

      Unintentional memory misalignment, which occurs when using the attributes 'pack_mode' or 'relative_offset'.

  • Use Empty Namespaces by Default (V2 Compatibility): Required when using a CODESYS V2-compatible OPC server configuration.

    : Behavior same as in CODESYS V2.3.

    • Program variables are exported without an application name (Application.PLC_PRG.MyVar –> PLC_PRG.MyVar

    • Global variables are exported additionally without the GVL name (Application.GVL.MyGlobVar –> .MyGlobVar

  • Enable Direct I/O Access: This feature is potentially dangerous and not intended for operation in production. Activate only for error checking and tests, or when commissioning the machinery (for example, for checking cables connections).

    : In the symbol configuration, you can also use access to direct I/O addresses that correspond to IEC syntax (for example, “%IX0.0”). Access to input addresses (I) is read-only*. Access to output addresses (Q) and memory addresses (M) can be read-write.

    *Information: In simulation mode, write access to symbols is also possible for input addresses.

    Because external clients for protocols such as OPC or OPC UA do not always support IEC syntax for direct addresses, access is also provided using an array syntax in the namespace __MIO of the implicit code. For example, you can also access __MIO.MIO_IX[2].x3 instead of %IX2.3.

    However, the symbols for array access are hidden in browsers because some clients cannot handle the large number of nodes (several thousand depending on the size of the I/O ranges).

  • Support Calls of Functions, FBs, Methods, and Programs:

    Note: Availability and editability of this option depend on the device.

    : The access rights execute can be set in the symbol table for symbols of POUs of type function, function block, method, or program. The Support OPC UA features option also has to be selected in the Settings.

  • Include Call information in XML:

    : The information about called functions, function blocks, methods, or programs is also listed in the XML file of the symbol configuration. The option is enabled only if the Support calls of functions, FBs, methods, and programs option is supported by the device.

  • Enable Symbol Sets:

    : A toolbar with buttons and a list box is displayed above the symbol table. You can use this to configure symbol sets for client-specific assignment of access rights to the controller. See “Toolbar for symbol set configuration” below.

Download

If you use a device that supports its own application file for the symbol configuration, then this button is also available in the toolbar. If you change the symbol configuration in online mode, then you can load the new <application name>._symbols file immediately to the PLC.

Tools

Save XSD Scheme File: This command opens the standard dialog for saving a file in the file system. With this command, you can prepare the XSD format of the symbol file, for example for use in external programs.
Symbol table

Access Rights

You can change the access rights for a symbol by clicking the symbol in the Access Rights column.

Icons for access rights (in ascending order)

  • : Read only

  • : Write only

  • : Read and write

  • : Execute

    This permission allow for execute access to functions, function blocks, methods, and programs.

    Requirements for the assignment: The device provides the Support calls of functions, FBs, methods, and programs and Support OPC UA features options. Both options are activated in the Settings.

Note: In case the controller has a user management, you can use symbol sets to define client-specific access rights to the same symbols.

Maximal

Maximum access rights for this symbol

Attribute

If the access right was assigned by attribute, then a corresponding icon is displayed here.

Type

Alias data types are also displayed In CODESYS V3.5 SP6 and higher. Example: MY_INT : INT for a variable declared with the data type MY_INT (type INT).

Members

You can add variables of a structured data type also by selecting a check box for symbol configuration in the Symbols column. This causes CODESYS to export all member variable symbols. However, in the Members column, you can click the ellipsis button () to select only specific structural components. Note: This selection applies to all instances of this data type for which symbols are exported. If a member of a structured type cannot be selected, then an asterisk () is displayed in the check boxes of the members to indicate that all exportable members of that type are exported.
Toolbar for symbol set configuration

List box

Already defined symbol sets

Add New Symbol Set

Opens the Add New Symbol Set dialog for specifying a name for this set

Add Duplicate from Selected Symbol Set

Opens the Add Duplicate from Selected Symbol Set dialog. A copy is created for the set selected in the list box. You can change the default name (<group name>_duplicate).

Rename Selected Symbol Set

Opens the Rename Selected Symbol Set dialog for specifying another name for the set selected in list box.

Delete selected Symbol Set

Opens a dialog prompting whether or not the symbol set selected in the list box should be deleted.

Configure Symbol Rights

Opens the Symbol Rights tab of the device editor. When logged in there, you can assign different access rights for each user group (client) to the symbol set selected in the list box.

See also

Dialog ‘Comments and Attributes’

Symbol Table Contents

Enable extended OPC UA information

Note: Availability and editability of this option depend on the device.

: Additional information that can be evaluated by OPC UA servers is included in the symbol table. This includes inheritance information of user-defined data types and the namespace node flags. Additional information, such as comments and attributes, can also be included if the OPC UA setting is active.

When the OPC UA setting is enabled, attributes are included in the symbol table according to the following rule:

  • In compiler versions V3.5.5.0 to V3.5.7.X, all attributes are included according to the Match simple identifiers setting.

  • In compiler version V3.5.8.X, all attributes are included according to the setting Include all attributes.

  • In compiler version V3.5.9.0 and higher, you can customize the attributes that are included.

Include comments

Requirement: Enable extended OPC UA information is activated.

: Comments and attributes are also saved in the symbol table.

Include attributes

Also include comments and attributes for type nodes

Requirement: Include comments is activated.

: The information for type nodes is also included (user-defined types, such as STRUCT and ENUM elements).

: Only directly exported variables have comments and attributes.
XML symbol file contents

Include namespace node flags

: The namespace node flags provide additional information about the origin of a node in the namespace. The node flags always in the symbol table when OPC UA is activated. However, its inclusion in the XML file can be deactivated as some defective parsers have problems with it.

Include comments

: Comments can also be saved in the XML file.

In compiler versions V3.5.5.x to V3.5.8.0, this includes the setting Prefer docu-comments.

Include attributes

: Attributes can also be saved in the symbol file.

Also include comments and attributes for type nodes

Requirement: Include comments is activated.

: The information for type nodes is also included (user-defined types, such as STRUCT and ENUM elements).

: Only directly exported variables have comments and attributes.
Select Comments

Requirement: Include comments is activated.

Include docu comments

Include normal comments

Always include both types of comments

Prefer docu comments, fallback to normal ones

Prefer normal comments, fallback to docu comments

The options determines the comments that are saved in the symbol configuration.
Filter Attributes (Case-Insensitive)

Requirement: Include attributes is activated.

Include all attributes

Include attributes starting with

Filter attributes with regular expression

Defines the attributes that are saved in the symbol configuration.

Match simple identifiers

Exists primarily due to the backward compatibility to older versions in order to emulate the old behavior.

Setting: Configure synchronization with IEC tasks

For synchronously consistent access, the symbolic client waits in the runtime when processing a read or write request until a time is found when no IEC task is executed. When this gap is detected, restarting the IEC tasks is prevented until all values of the variable list have been copied. Then the IEC tasks are planned again as usual. Synchronized access can cause a delayed starting of IEC tasks, which is shown as increased jitter. As all applications in the runtime are managed by a common scheduler, this potential impairment of the real-time behavior affects all applications on the device. All applications of the device are affected, regardless of whether or not they include a symbol configuration or they have been downloaded to the controller from one or more CODESYS projects. Therefore, the runtime permits synchronized consist access only if this it allows all applications that are downloaded to the controller at the time of access.

Note

The setting is located in the editor of the symbol configuration of the Settings menu. In addition, the setting is also located in the context menu of the controller when you click the Properties command and then select the Options tab in the opened dialog.

For applications without symbol configuration, the setting can only be found in the properties dialog.

Hint

After changing the setting, all applications downloaded to the device by means of a download or online change have to be reloaded and all boot applications updated.

In which cases is synchronized consistent access necessary?

As a rule, there is no need for consistent values for displayed values because it is mostly irrelevant from which IEC task cycle the changed values originate. It is completely irrelevant for seldom changed values. Even when writing there are almost no hard consistency demands because typically the machine must be in a kind of standby mode (for example when writing recipes) in which there is no direct access to the values written as recipes.

In contrast, consistent values are particularly necessary for database links to save production data. For clocked machines, however, these values must be synchronous with the production timing (one value set per produced product) and not consistent with reference to one or more IEC tasks. With reference to the machine clocking, the consistency must be already ensured by the IEC application. For this purpose, the values that arise during a production cycle are typically collected in a global variable list. At the end of the cycle, the symbolic client is notified by means of an additional variable (BOOL or counter) that the machine cycle has ended and the values are valid. Now the client has the chance to archive the values from the production cycle. Depending on necessity, the successful reading can also be displayed in the opposite direction by means of a released variable, so that the production can also be halted in case the production data cannot be archived. Synchronized consistent access is not necessary and helpful for this use case because the synchronization takes place at the application level.

In contrast, synchronized consistent access by symbolic clients is typically applied in the process industry with continuously running systems without production clocking when, for example when process values are written consistently and cyclically in a fixed time frame of 60s. This can take place either by synchronization on the application level similar to clocked machines (see above) or by synchronization of the synchronized consistent symbolic access. The advantage of the latter is that no logic has to be implemented in the IEC program and access is controlled entirely by the client.

Caution

Due to the increased jitter, the synchronized consistent monitoring is not suitable for motion or real-time critical applications. For these reasons, synchronized consistent access should be released and used only if it is absolutely necessary.

If a client uses synchronous consistent access released by this setting, then it has and effect on the client. Depending on the scheduler of the runtime, the response time can jitter more here for read/write access because the system might still have to wait for an execution gap of the IEC tasks. Read and/or write access can still fail when IEC tasks run for a long time (in the range of several 100 ms) or the CPU load is close to 100% for an extended period of time with one or more IEC tasks (in the range of several 100 ms). Therefore, the availability of the values also depends on the load of the controller by the IEC application.

Moreover, the client can minimize the effects on itself and on the runtime if it observes the following in the definition of the variable lists to be read or written:

  • Synchronized consistent access only to those variables that are absolutely and consistently required.

  • Separate variable lists for variables that have to be consistent and for variables that could be inconsistent.

  • Divide variable lists with several consistent variables into several smaller lists.

  • Select read intervals for cyclic reading of values as large as possible.

Support for the current configuration and possible corrective actions

Entries marked in red in the symbol table show variables that they are configured for export to the symbol file but are currently invalid in the application. The cause for this can be that the declaration has been removed from the block.

In version 3.5.8.0 and higher, a warning appears in the editor if variables that have configured symbols are not used in the IEC code or are not mapped in the case of I/O variables. In addition, the compiler indicates variables that are referenced from outdated library versions n the symbol configuration.

Hint

Object variables that are not used in the program code remain uncompiled by default and are therefore not available in the symbol configuration.

However, CODESYS provides variables from uncompiled objects in the symbol configuration when one of the following conditions is met:

  • The Link always POU property is selected.

  • The {attribute 'linkalways'} pragma is used.

See also

Example for the data layout types

Examples for the layout types

The following examples from an IEC application will show how gaps can result in the client-side memory layout caused by unpublished symbols, internal “invisible” pointers, or a “pack mode” definition in the device description. With the Optimized layout setting, the gaps are avoided. The symbol file contains different information about the size and offset of memory locations, depending on the selected layout setting.

Example: Large structure

// Example of a big structure, where not all members get published :
STRUCT
        {attribute 'symbol':='readwrite'}
        PublicNumber : INT;

        {attribute 'symbol':='none'}
        InternalData : ARRAY[0..100] OF BYTE;

        {attribute 'symbol':='readwrite'}
        SecondNumber : INT;

        {attribute 'symbol':='none'}
        MoreData : ARRAY[0..100] OF BYTE;
END_STRUCT
END_TYPE

Resulting entries in the symbol file; pay attention to “size” and “byteoffset”:

Symbol file, large structure, compatibility layout option

<TypeUserDef name="T_LargeStructure" size="208" nativesize="208" typeclass="Userdef" pouclass="STRUCTURE" iecname="LargeStructure">

<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" />

<UserDefElement iecname="SecondNumber" type="T_INT" byteoffset="104" vartype="VAR" />

</TypeUserDef>

Symbol file, large structure, optimized layout option

<TypeUserDef name="T_LargeStructure" size="4" nativesize="208" typeclass="Userdef" pouclass="STRUCTURE" iecname="LargeStructure">

<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" />

<UserDefElement iecname="SecondNumber" type="T_INT" byteoffset="2" vartype="VAR" />

</TypeUserDef>

Example: Structure with uneven addresses

// The following mechanisms can cause memory misalignment:
// - {attribute 'relative_offset':='…'} at a member
// - {attribute 'pack_mode':='…'} at a structure declaration
// - target setting 'memory-layout\pack-mode' in the device description

{attribute 'pack_mode':='1'}
TYPE UnevenAddresses:
STRUCT
        {attribute 'relative_offset':='3'}
        {attribute 'symbol':='readwrite'}
        PublicNumber : INT;

        {attribute 'symbol':='readwrite'}
        PublicValue : LREAL;
END_STRUCT
END_TYPE

Resulting entries in the symbol file; pay attention to “size” and “byteoffset”:

Symbol file, structure with uneven addresses, compatibility layout option

<TypeUserDef name="T_UnevenAddresses" size="13" nativesize="13" typeclass="Userdef" pouclass="STRUCTURE" iecname="UnevenAddresses">

<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="3" vartype="VAR" />

<UserDefElement iecname="PublicValue" type="T_LREAL" byteoffset="5" vartype="VAR" />

</TypeUserDef>

Symbol file, structure with uneven addresses, optimized layout option

<TypeUserDef name="T_UnevenAddresses" size="16" nativesize="13" typeclass="Userdef" pouclass="STRUCTURE" iecname="UnevenAddresses">

<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" />

<UserDefElement iecname="PublicValue" type="T_LREAL" byteoffset="8" vartype="VAR" />

</TypeUserDef>

Example: Function block

// Each POU contains some implicit variables, which do not get published. Depending on the data type these might cause memory gaps of different sizes.
FUNCTION_BLOCK POU IMPLEMENTS SomeInterface
VAR_INPUT
        in : INT;
END_VAR
VAR_OUTPUT
        out : INT;
END_VAR
VAR
END_VAR

Each POU contains some implicit variables, which do not get published. If it is a data type such as __XWORD, then different sizes of memory gaps result in the client-side data layout, depending on whether the system is 64-bit or 32-bit.

Resulting entries in the symbol file for 64-bit and 32-bit; pay attention to “size” and “byteoffset”:

Symbol file, function block, compatibility layout option, 64-bit

<TypeUserDef name="T_POU" size="24" nativesize="24" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="POU">

<UserDefElement iecname="in" type="T_INT" byteoffset="16" vartype="VAR_INPUT" />

<UserDefElement iecname="out" type="T_INT" byteoffset="18" vartype="VAR_OUTPUT" />

</TypeUserDef>

Symbol file, function block, optimized layout option, 64-bit

<TypeUserDef name="T_POU" size="4" nativesize="24" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="POU">

<UserDefElement iecname="in" type="T_INT" byteoffset="0" vartype="VAR_INPUT" />

<UserDefElement iecname="out" type="T_INT" byteoffset="2" vartype="VAR_OUTPUT" />

</TypeUserDef>

Symbol file, function block, compatibility layout option, 32-bit

<TypeUserDef name="T_POU" size="12" nativesize="12" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="POU">

<UserDefElement iecname="in" type="T_INT" byteoffset="8" vartype="VAR_INPUT" />

<UserDefElement iecname="out" type="T_INT" byteoffset="10" vartype="VAR_OUTPUT" />

</TypeUserDef>

Symbol file, function block, optimized layout option, 32-bit

<TypeUserDef name="T_POU" size="4" nativesize="12" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="POU">

<UserDefElement iecname="in" type="T_INT" byteoffset="0" vartype="VAR_INPUT" />

<UserDefElement iecname="out" type="T_INT" byteoffset="2" vartype="VAR_OUTPUT" />

</TypeUserDef>

See also