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.

Note

If you use a Device application, the following applies: The device application itself cannot have a symbol configuration. However, symbols from the device application are offered for selection in the symbol configurations of their child applications.

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

Dialog ‘Add symbol configuration’

Function: This dialog is used for defining presets for a Symbol configuration object.

Call: Menu bar Project ‣ Add object ‣ Symbol configuration ; context menu of the application object.

Include comments in XML CODESYS 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
  • Variable type (INPUT / OUTPUT / IN_OUT)
Add library placeholder to device application (recommended, but can trigger a download)

This option is relevant when a Device application is used:

The library references for the symbol configuration libraries, which are present in the library manager below the application, are also inserted into the library manager of the device application. The advantage of this is that the library data must no longer be downloaded with the application to the controller. They are downloaded one time with the device application as the other global data. For more information, refer to the section on using a device application.

See also

Client side data layout
For detailed information and examples of layout options, refer to 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 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 data type alignment. Requires compiler version 3.5.7.0 or later.

Symbol configuration editor

This editor includes a table with the selected variables, a menu bar for editing, a CODESYS with supporting information, and buttons for required actions.

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 causes CODESYS to also list the variables that have already been marked for export in the symbol file by means of the {attribute 'symbol' := 'read'} pragma. These symbols are marked in gray. The Attribute column shows which access rights are set by the pragma.
Create Project build: 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 data 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
    • Variable type (VAR_INPUT / VAR_OUTPUT / VAR_IN_OUT)

  • <!> Include comments in XML: CODESYS exports the symbol file with the comments assigned to the variables.

  • Record 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: In the Comments and attributes dialog, you configure the contents in the symbol configuration and the XML file.

  • Configure synchronization with IEC tasks: Opens the Properties - <PLC 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, refer to section “Setting: Configuring Synchronization with IEC Tasks” 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.

  • Selection for the type of data layout that should be created for the client of the symbol configuration:

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

    • 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: Memory gaps by internal pointers or references in POUs and by structure members that are not released in the symbol configuration; depending on data type (__XINT, __XWORD, etc.) also different memory gaps for 32-bit and 64-bit systems; fields on uneven addresses that some clients are not equipped for; unintentional incorrect alignment by using the attributes pack_mode or relative_offset.

    • 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 data type alignment. Requires compiler version 3.5.7.0 or later.

  • 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 option Support OPC UA features also has to be activated in the Settings.
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 XML 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.

Add library placeholder to device application (recommended, but can trigger a download): This option is relevant when a Device application is used. The library references for the symbol configuration libraries, which are present in the library manager below the application, are also inserted into the library manager of the device application. For more information, refer to the description of the same-named option in the Add symbol configuration dialog.
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

  • : read only

  • : write only

  • : read and write

  • : execute

    These rights allow for executing access to functions, function blocks, methods, and programs.

    Requirements for the assignment: The device provides the options Support calls of functions, FBs, methods, and programs and Support OPC UA features. Both options are activated in the Settings.
Maximum Maximum access rights
Type Alias data types are also displayed In CODESYS Development System V3.5 SP6 and later. Example: MY_INT : INT for a variable declared with the data type MY_INT (type INT).
Member variables 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. Please 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.

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 activated, 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 setting Select simple names.
  • In compiler version V3.5.8.X, all attributes are included according to the setting Link all attributes.
  • In compiler version V3.5.9.0 and later, 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 The options determines the comments that are saved in the symbol configuration.
Normal comments  
Always include both types of comments  
Prefer docu comments, fallback to normal ones  
Prefer normal comments, fallback to docu comments  
Filter Attributes (case insensitive)
Requirement: Include attributes is activated.
Include attributes Determines the attributes that are saved in the symbol configuration.
Include attributes starting with  
Filter Attributes with regular expression  
Select simple name 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 system 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 scheduled again as usual. The synchronized access can cause a delayed starting of IEC tasks, which is shown as increased jitter. As all applications in the runtime system 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 system 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 can be made in the editor of the symbol configuration or in the Properties dialog of the controller (Options tab). (For applications without a symbol configuration, the setting is in the properties dialog only.)

Hint

After changing the setting, all applications downloaded to the device by means of a download or online change must 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 visualized 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 if 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, cyclic in a fixed time frame (e.g. 60s) processes values should be consistently written. This can take place either by synchronization on the application level similar to clocked machines (see above) or by those of synchronized consistent symbolic access. The advantage of the latter is that no logic has to be implemented in the IEC program and access can be 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. Even here, depending on the scheduler of the runtime system, the response time can jitter more 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 system 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 later, 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 block property is selected.
  • The {attribute 'linkalways'} pragma attribute 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 setting Optimized layout, 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 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>