Data Persistence¶

The lifespan of a variable and its data begins at the time when the variable is created and ends at the time when the variable is deleted and its memory is freed. The time when the variable is created, initialized, or instantiated depends on the declared scope. The time when the memory is freed usually depends on the scope as well. For example, the memory of global variables is freed by exiting the application.

They can retain data longer than usual. The following mechanisms are provided for this purpose.

Mechanisms for data retention

(A): Persistent global variable list with the keyword PERSISTENT RETAIN

Persistent variables retain their values when the application is reloaded. Moreover, the values are restored after a download, warm start, or cold start.
(B): Retain variables with the keyword RETAIN

Retain variables retain their values after a warm start, but not after reloading the application, a download, or a cold start.
(C): Variables of the Persistence Manager of the CODESYS Application Composer

Variables of the Persistence Manager are stored in an external file.
(D): Recipe variables

Recipe variables and their values are stored in a recipe file.

Mechanisms in Comparison ¶

Which mechanism is suitable for which application? Some common use cases are considered in the table. The specific examples refer to a building control system.

Comparison of mechanisms and use cases¶
	Uses case	Persistent variables	Retain variables	Variables of the Persistence Manager	Recipe variables
1	The application must maintain device settings. Example: After a power failure, the building control has to have information available about how long a window blind needs to be raised.	Suitable¹ Preferred use case In this case, you can also use retain variables instead of persistent variables. This is advantageous for variables whose declaration is often changed.	Suitable Preferred use case Retain variables are an advantage when their declarations are changed often.	Suitable² This is advantageous for controllers that do not have any hardware support. Special functionalities make this possible, such as double file buffering.	Possible, but very complicated and therefore not recommended.
2	The application must maintain values also after program changes or extensions.
	2a: Rare extensions Example: An application programmer extends the program with a new switch and installs a new light. The building control must still have saved values available until then.	Suitable¹ Preferred use case	Suitable	Suitable²	Possible, but complicated.
	2b: Unrestricted changes, including deleting or changing the data type of variables The building control is running and is persistent. When an application programmer adds a new functionality to the controller and therefore adds another persistent variable to a function block, the values saved up to that point must be retained. For example, the program in an FB is extended with a variable that controls the automatic switching off of a previously uncontrolled lamp after a certain time. The building control must have the times of all controlled lamps available after the extension.	Not suitable	Suitable Data from retain variables are preserved as far as possible after an online change.	Suitable as far as possible ² Preferred use case	Possible if textual, but complicated
	2c: The application must maintain values after a download.	Suitable	Not suitable	Suitable	Suitable
3	The application must be able to use different value sets. Example: The operating settings for summer, winter, and holidays must be saved and imported when needed.	Not suitable	Not suitable	Not suitable	Suitable Preferred use case
4	The application must be able to use settings from another system. It must be possible to transfer settings to another plant using similar variables.	Not suitable	Not suitable	Suitable²	Suitable³
5	The application must provide human readable data. The user must be able to read, compare, and edit the data.	Not suitable	Not suitable	Suitable²	Suitable³

¹ Disadvantage: Only possible if the runtime system supports this mechanism and an NVRAM memory or UPS is available. Advantage: Speed; recommended application: 1 and 2a

² Disadvantage: In the case of large variable sets (> 10000), long delays during initialization and shutdown are to be expected. Advantage: No special memory is required; value retention exists even in case of changes, extensions, or deletions.

³ Advantage: Editable remotely, transferable. Disadvantage: Complicated

Lifespan of variables when calling online commands ¶

User input in the Online menu	Variable with usual lifespan Neither `RETAIN` nor `PERSISTENT`	`RETAIN`	`PERSISTENT` `RETAIN PERSISTENT` `PERSISTENT RETAIN`
Command Online Change	x	x	x
Command Reset warm		x	x
Command Reset cold			x
Command Download			x ¹
Command Reset origin

x : Variable retains its value

: Variable is initialized

¹ Note: For the structure of persistent data, refer to the information in “Mechanism for downloading”.

Lifespan of variables when downloading a boot project ¶

The values of ordinary variables lose their value and are reinitialized.

The values of persistent variables are protected when:

The structure of the persistent variable in memory matches the structure in the persistent data list.

The values of retain variables are protected when:

The structure of the persistent variable in memory matches the structure in the persistent data list.
The persistent variables match the application (GUID has to agree).

A “Retain mismatch” occurs when the requirements for restoring the values of retain variables and persistent variables are not met when the application is booted. The response to this discrepancy is described in the documentation of the hardware manufacturer.

Note: For the structure of persistent data, refer to the information in “Mechanism for downloading”.

Data Persistence¶

Mechanisms in Comparison¶

Lifespan of variables when calling online commands¶

Lifespan of variables when downloading a boot project¶

Mechanisms in Comparison ¶

Lifespan of variables when calling online commands ¶

Lifespan of variables when downloading a boot project ¶