Object: Symbol Configuration

You can use the symbol configuration to create symbol descriptions for project variables. Click Project → Add Object to add a symbol configuration object to the device tree, and then define specific default settings.

Tip

For providing symbols to an OPC UA Server, we recommend using the new configuration editor (IEC Symbol Set Configuration) for CODESYS 3.5 SP18 and higher.

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)

Table 6. Client-side data layout

For more 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.

Table 7. 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 Unaligned data only with unaligned memory access If the symbol configuration contains unaligned values or symbols for a device which does not support the required (unaligned) memory access, an error is set. The following message is displayed: The component <name> of the SymbolType <symbol type name> without memory alignment cannot be published. This prevents potentially faulty code from being downloaded to the controller, which could lead to an unpredictable crash of the controller.
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. When you change the symbol configuration in online mode, you can download the new `<application name>._symbols` file immediately to the PLC.
Settings	Support OPC UA features: Note: Availability and editability of this option depend on the device. For providing symbols to an OPC UA Server, we recommend alternatively using the new configuration editor (IEC Symbol Set Configuration) for CODESYS 3.5 SP18 and higher. : 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 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, embedding in the XML file can be disabled. Some parsers have problems with this. 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 symbolic clients (for example, visualizations or database connections based on the PLC handler) to have consistent read or write access which is synchronized with the IEC tasks. A detailed description of this setting can be found below in the section Setting: Configure synchronization with IEC tasks. 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: Also see the section Examples for the data layout types. 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 which occur differently in 32-bit and 64-bit systems depending on the data type, such as `__XINT` / `__XWORD` Fields which 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. Enable Direct I/O Access: Warning This feature is potentially dangerous and not intended for operation in production. Enable 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.
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.

Table 8. 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 allows for execute permission 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 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.

Table 9. 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.

For more information, see: Tab: Symbol Rights

Dialog: Comments and Attributes

Table 10. 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.

Table 11. 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	: 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.

Table 12. 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.

Table 13. 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 allows synchronized consist access only if this it allows all applications that are downloaded to the controller at the time of access.

Tip

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.

Important

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 is performed 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 be done 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 an 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.

Important

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 still 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.

For more information, see: Dialog: Properties: Build and Dialog: Properties: Options: Controller

Examples for the data layout types

Example 10. Large structure

Example of a large structure, not all members of which are 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"):

Example 11. Symbol file, large structure, compatibility layout option

<TypeUserDef name="T_GrosseStruktur" size="208" nativesize="208" typeclass="Userdef" pouclass="STRUCTURE" iecname="GrosseStruktur">
<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" />
<UserDefElement iecname="SecondNumber" type="T_INT" byteoffset="104" vartype="VAR" />
</TypeUserDef&gt>

Example 12. Symbol file, large structure, optimized layout option

<TypeUserDef name="T_GrosseStruktur" size="4" nativesize="208" typeclass="Userdef" pouclass="STRUCTURE" iecname="GrosseStruktur">
<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" /&lt;UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" />
<UserDefElement iecname="SecondNumber" type="T_INT" byteoffset="2" vartype="VAR" />
</TypeUserDef>

Example 13. Structure with uneven addresses

The following mechanisms may result in members with memory misalignment:

{attribute 'relative_offset':='…'} on a member

{attribute 'pack_mode':='…'} in a string declaration

Target setting 'memory-layout\pack-mode' in the device description

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

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

Resulting entries in the symbol file; (pay attention to "size" and "byteoffset"):

Example 14. Symbol file, structure with uneven addresses, compatibility layout option

<TypeUserDef name="T_UngeradeAdressen" size="13" nativesize="13" typeclass="Userdef" pouclass="STRUCTURE" iecname="UngeradeAdressen">
<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="3" vartype="VAR">
<UserDefElement iecname="PublicValue" type="T_LREAL" byteoffset="5" vartype="VAR" />
</TypeUserDef>

Example 15. Symbol file, structure with uneven addresses, optimized layout option

<TypeUserDef name="T_UngeradeAdressen" size="16" nativesize="13" typeclass="Userdef" pouclass="STRUCTURE" iecname="UngeradeAdressen">
<UserDefElement iecname="PublicNumber" type="T_INT" byteoffset="0" vartype="VAR" />
<UserDefElement iecname="PublicValue" type="T_LREAL" byteoffset="8" vartype="VAR" />
</TypeUserDef>

Example 16. 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 POUx 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_Baustein" size="24" nativesize="24" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="Baustein">
<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_Baustein" size="4" nativesize="24" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="Baustein"&gt;>
<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_Baustein" size="12" nativesize="12" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="Baustein">
<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_Baustein" size="4" nativesize="12" typeclass="Userdef" pouclass="FUNCTION_BLOCK" iecname="Baustein">
<UserDefElement iecname="in" type="T_INT" byteoffset="0" vartype="VAR_INPUT" />
<UserDefElement iecname="out" type="T_INT" byteoffset="2" vartype="VAR_OUTPUT" />
</TypeUserDef>

For more information, see: Symbol Configuration.

Object: Symbol Configuration

Tip

Dialog: Add Symbol Configuration

Symbol configuration editor

Unaligned data only with unaligned memory access

Warning

Dialog: Comments and Attributes

Setting: Configure synchronization with IEC tasks

Tip

Important

Caution

Support for the current configuration and possible corrective actions

Important

Examples for the data layout types