Extended Retain Handling

This topic contains the following sections:

What is retain data?

Besides the volatile memory (usual RAM), a controller offers a retain memory. Values stored in the RAM are lost after a power down. Values stored in the retain memory, however, are kept during power down and can therefore be restored on power return.

The technical implementation of the retain memory (for example, by an integrated NVRAM or via storage of a retain data file on an SD card plugged into the controller) depends on the PLCnext Technology controller used. For normal operation, the implementation does not matter. It is, however, relevant in case of replacing a defective controller.

According to the IEC 61131-3 standard, variables and ports which should be stored in the retain memory must be declared with the 'Retain' keyword (see topic "Variable/Port Properties".) The Data List uses this as column header. In C# libraries, the attribute GdsRetain must be used.

The PLCnext Technology runtime calculates a CRC for the retain memory layout out of the retain variables. This Retain CRC is stored together with the retain value in the retain memory. The firmware performs this backup automatically before each cold restart.

At power-on, the runtime first attempts a warm restart by default which can be performed if the CRC in the retain memory matches to CRC of the currently loaded project.

Extended retain handling (as of PLCnext firmware version 2020.6)

A modification of the retain data of the controller program, for example, by inserting, changing or deleting retain variables or related data types, results in a different CRC. After transferring to the controller (using the 'Write and Start' command or by copying binary files while the controller is stopped), the runtime recognizes the differing CRC and detects the changes in the memory layout of the retain variables.

The reaction of the PLCnext runtime on such changes depends on the firmware version: Firmware versions up to 2020.3 react by performing a cold restart even if a warm restart has been requested. Firmware versions 2020.6 and newer are offering the extended retain handling mechanism as described below.

Note
The Safety PLC does not support the extended retain handling.

Without the extended retain handling, the modification of retain data in an application (see scenario described above), would require a controller cold start. The reason for this is that addresses at which the modified program expects the retain variables in the controller memory may have been changed by the program modifications and the subsequent compilation.

The Extended retain handling preserves the value of each retentive variable without assigned process data item by loading it from the controller before the modified and newly compiled project is written to the controller. After writing the changed program to the controller, the system "re-downloads" the previously saved variables values to the corresponding memory addresses.

The extended retain handling mechanism attempts to keep as much retain values as possible.
For that purpose, the PLCnext runtime stores the memory layout of the retain variables in a file when the project is loaded. Next time a project is loaded the previously stored memory layout file is used to detect changes in the retain memory layout. Then, the PLCnext runtime uses the detected changes in the layout to keep as much values as possible.

Preconditions: The retain data can only be restored if the Retain CRC of the project to be executed and the backed up Retain CRC are identical. An identical CRC is only calculated under the following conditions:

The project name remains the same.
The file which contains the memory layout information and the CRC calculated from there is available and can be read.
The CRC matches the corresponding CRC stored in the retain memory layout information.

Otherwise, a cold restart will be performed (no values are retained). Applied rules:

A new retain variable is always initialized with its initial value (no values are retained). If no initial value was assigned in the declaration, the default value according to its data type is used.
If the name of a retain variable is modified, the variable is considered as new. Reason: the retain handling identifies each retentive variable by its instance path.
The same applies if the name of a program or FB instance is modified: all contained variables and child instances are regarded as new variables.
If the data type of a retain variable is changed the behavior of the extended retain handling depends on the "old" and the "new" data type:
- Elementary data types: The PLCnext runtime keeps the value if both are elementary data types (except for String) and the old data type can be converted to the new data type without any loss of range and precision. Here, the mechanism of GDS connections is used.
- User-defined data types (String, Arrays, and Structs): all elements are initialized.
- Deleted retain variables are not considered by the retain handling. However, it may be possible that remaining retain variables get displaced in the memory image on the controller.
- Retain variables may be displaced in the memory image on the controller by inserting variables, deleting variables and moving variables within a variables grid.
If the definition of a user-defined data type itself is changed the above rules are applied member-wise. This applies even if the name of the variable or data type remains unchanged.
In arrays each element is identified by its index.
In C++/C# programming, an array starts with index 0. Elements can be added or deleted, and on warm restart the overlapping items of the index retain their values.
In IEC 61131-3 programming, an array is defined by the first ("lower bound") and last ("upper bound") index item. That results in this specific behavior:
- If an array is enlarged, the added items are initialized on startup while already existing values keep their retains values.
  Example: array[4..10] is enlarged to array[3..11]. Elements 3 and 11 are initialized, elements 4 to 10 are retained.
- If an array is moved into another array, only the overlapping elements (with already existing index) retain their values. The other values are initialized, or (as shown in the following example) they will be deleted.
  Example: array[4..10] is moved to array[7..13]. Only the elements 7 to 10 retain their values (even though the array consists of 7 items before and after the change). Elements 4..6 are lost and the added items 11 to 13 are initialized.
For nested complex data types, the above rules are applied recursively.

Saving/Loading Retain Data out of the Controller Cockpit

The retain handling described above is executed automatically by the controller runtime. There is no need to intervene manually.
In addition, you have the possibility to backup and restore the retain data of your application. This way, you can "preserve" a particular condition of your application at a desired point in time. If required, you can reload the saved retain values and continue the application at the preserved state. By copying the backup file to an SD card, retain values can, for example, be reused after a controller replacement or transferred to different controllers/applications.

To this end, the 'Cockpit' toolbar of PLCnext controllers (as of firmware version 2020.6) provides the following commands:

Note
These commands are not available in the Safety Cockpit as the Safety PLC does not support the extended retain handling.

Saves the retain data to a backup file.
This command is available while the controller is connected to PLCnext Engineer and you are logged on to the controller. The command can be executed independently of the controller state.

Note
Make sure that no retain data is changed in the project while the backup is stored. This can, for example, be ensured by setting the controller to Stop state before clicking the button.

Clicking the button writes the values of all retentive variables to a file. The name of the backup file (*.prb) is composed of the current date and time as well as the name of the user who is currently logged on.
Up to 10 backup files are possible. Each further backup overwrites the oldest file.

Restores the latest retain data from a backup file.
The command is only available while the controller is connected to PLCnext Engineer and in Stop state, and you are logged on to the controller.
Clicking the button preloads the last saved retain values from the backup file and then executes an extended warm start.

Note
Restoring backed up retain data this way is only possible if the project name and the Retain CRC are the same. See section "Preconditions" above.