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 RETAINPersistent 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
RETAINRetain 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.
|
Uses case |
(A) Persistent variables |
(B) Retain variables |
(C) Variables of the Persistence Manager |
(D) 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. |
Suitable1 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. |
Suitable2 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. |
Suitable1 Preferred use case |
Suitable |
Suitable2 |
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 2 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 |
Suitable2 |
Suitable3 |
|
5 |
The application must provide human readable data. The user must be able to read, compare, and edit the data. |
Not suitable |
Not suitable |
Suitable2 |
Suitable3 |
1 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
2 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.
3 Advantage: Editable remotely, transferable. Disadvantage: Complicated
Lifespan of variables when calling online commands
|
User input in the “Online” menu |
Variable with usual lifespan Neither |
|
|
|---|---|---|---|
|
Command “Online Change” |
x |
x |
x |
|
Command “Reset Warm” |
i |
x |
x |
|
Command “Reset Cold” |
i |
i |
x |
|
Command “Download” |
i |
i |
x 1 |
|
Command “Reset Origin” |
i |
i |
i |
x : The variable retains its value.
i : The variable is initialized.
1 Note: For the structure of persistent data, see 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".
See also