Retain variables in Extended Retain Handling

General retain memory concept

Traditionally a PLC offers two types of memory:

• Volatile memory: values are lost on power down (usual RAM). 
• Retain memory: values are kept during power down so these values can be restored on power return.

Usually a PLC offers much more volatile memory than retain memory. PLCnext Control devices are using two different mechanism to implement retain memory for when the PLC is stopped and when power is lost. Some controllers like AXC F 1152 and AXC F 2152 use a dedicated NVRAM hardware, other controllers like AXC F 3152 and RFC 4072S store the values of retain variables in a file (see controller-specific features).

Normally you do not have to care which mechanism is used by your controller. Only in case of replacing a defect controller this comes into mind because the NVRAM implementation stores the retain values at the device and they get lost with the defective controller. The file implementation combined with using an SD card stores the retain values at the SD card and the retain values are transferred to the new controller by plugging in the SD card from the defective controller.

According to IEC 61131, variables which should be stored in retain memory are defined with the keyword “RETAIN” (PLCnext Engineer’s data list uses this as the column header). PLCnext Technology transfers this approach to C++ and C# programming as an attribute (Retain in C++, and respectively GdsRetain in C#) for variables and ports.

Furthermore, IEC 61131 defines three start modes:

• Cold Restart initializes all variables
• Warm Restart initializes only variables which are not indicated as “RETAIN”
• Hot Restart initializes no variables

The PLCnext Runtime calculates a CRC for the retain memory layout out of the retain variables. This CRC is stored together with the retain value in the retain memory. At power-on, the PLCnext Runtime 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.

So far this is quite easy to understand.

It becomes a little more difficult when the retain portion of the PLC program is changed, for example by inserting, changing or deleting retain variables or related data types. When such changes are transferred to the PLC by Download All in PLCnext Engineer or by copying binary files while the PLC is stopped, the PLCnext Runtime detects changes in the memory layout of the retain variables and reacts depending on the firmware version:

• Firmware version up to 2020.3 reacts by performing a Cold Restart even if a Warm Restart has been requested.
• Firmware version 2020.6 and newer are offering a more sophisticated mechanism called Extended retain handling.

Extended retain handling 

Available from 2020.6

This approach attempts to keep as much retain values as possible. Therefore, 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 RetainMemoryLayout. Then, the PLCnext Runtime uses the detected changes in the layout to keep as much values as possible, following these rules:

• Extended Retain Handling is applied only if the project name remains the same.
• Extended Retain Handling cannot be applied:
  • if the file which contains the memory layout information and the CRC calculated from there is missing; a Cold Restart will be performed, so no values are retained.
  • if the CRC does not match to the corresponding CRC stored in the RetainMemoryLayout information; a Cold Restart will be performed, so no values are retained.
• A new variable is always initialized with its initial value, so no values are retained. After changing the variables name, this variable is regarded as a new variable because a variable is identified by its name and instance path (e.g.: componentInstance.programInstance.fbInstance.fbInstance...). Similarly, if the name of a program or function block instance is changed then 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 data types used before and after the change:
  • If both are elementary data types (except for String), the PLCnext Runtime keeps the value if 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.
  • For String, Array, and Struct, all elements are initialized.
• If the definition of a user-defined data type itself is changed – even if the variable's naming or data type's naming stays the same – the above rules are applied member-wise.
• For nested complex data types, the above rules are applied recursively.
• For arrays each member is identified by its index:
  • In C++/C# programming, an array starts with index 0. Members 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 array[4..10] is enlarged to array[3..11] the added items 3 and 11 are initialized on startup while the items 4 to 10 retain their values.
    • If array[4..10] is moved to array[7..13] only the items 7 to 10 retain their values. That is, even though the array consists of 7 items before and after the change. Items belong to their specific positions in the index so the values of the deleted items 4..6 are lost while the added items 11 to 13 start with initial values.

Known issues in retain handling

Backup and restore retain variables 

Available from 2021.0 LTS

As described above, the extended retain handling keeps as much values of the variables that are selected as retain variables as possible when downloading another version of the same project to the controller.

In addition to the the extended retain handling, the backup and restore feature allows to save and restore variable values if

• an unintentional Cold Restart of the controller has been performed
• a wrong project has been downloaded to the controller by accident
• a defect device that stores the retain variable values to NVRAM (e.g. AXC F 1152 or  AXC F 2152) shall be replaced

Backup of retain values

The retain variable values and the CRC for the retain memory layout are stored along with the project name into a backup file. Up to 10 backup files are possible (automatically and manually generated backup files together) . Before the eleventh file is generated, the oldest file is deleted. The criterion is the file name without the Cold / User indication (Cold = automatic and User = manual backup).
A backup file with all the values before the last restart is saved on the internal file system of the controller under /opt/plcnext/retaining/backups. 

Automatic backup

This backup is performed automatically before each Cold Restart.

The name pattern of the automatically generated backup file before the cold start is as follows:

YYYY_MM_DD_hh_mm_ss_Cold

Manual backup

The backup can also be created manually using PLCnext Engineer. The retain values must not be changed during the backup process. For this reason, the backup option is only available when the controller is in STOP state. Proceed as follows:

• Set the controller to the STOP state.
• To create a backup, use the button  in the cockpit of PLCnext Engineer. 
  Cockpit in PLCnext Engineer with backup buttonShow backup button in the PLCnext Engineer cockpit 

  

The name pattern of the manually generated backup file via PLCnext Engineer is as follows:

YYYY_MM_DD_hh_mm_ss_User

Restore retain values

Restore latest backup 

The retain variable values in a backup file can be restored via PLCnext Engineer. The retain values must not be changed during the restore process. For this reason, the restore option is only available when the controller is in STOP state. Proceed as follows:

• Set the controller to the STOP state.
• To restore the latest backup, use the button  in PLCnext Engineer.
  Cockpit in PLCnext Engineer with restore buttonShow restore button in the PLCnext Engineer cockpit

  

After the retain values have been restored successfully, a warm start is performed and the following notification is displayed in the lower right corner of the screen in PLCnext Engineer: 
The retain data was restored successfully.  

By default the newest backup file is used to restore the variable values. It is identified via the file name without the Cold / User indication. 
The project name and CRC must also match in order to restore the data. 

If restoring the data fails, a desktop alert is displayed in the lower right corner of the screen: Cannot restore retain data. The controller remains in the STOP state.

Restore any backup file 

If you want to use a backup file other than the latest one, you must currently change the file name of this backup file so that it is the latest one. For example, by increasing the year number in the file name. At this point only a sorting without plausibility check takes place.

You can find the backup files under /opt/plcnext/retaining/backups on the file system of your controller.

 

 

• Published/reviewed: 2024-10-30   ☀  Revision 074 •