Retain Variables

A retain variable is a PLC variable which:

  • Is non-volatile and stored in non-volatile controller memory (PCMM2G).
    • When using the KAS Simulator, the retain variables are stored in a normal disk file.
  • Is known by all programs (when its content is changed, the change is propagated to all equations in which this variable is used)
  • Normally does not contain real-time critical data.

    • Retain variables are saved when you stop the PLC.
    • The next time the PLC starts, the retained values are used.
    • Retains are auto-saved every two seconds.
      • Changed variables stored in non-volatile memory are updated every two seconds.
      • Unchanged variables are not updated.

Retain variables are typically used to store application-specific persistent state.

Example: Counting cutting edge cycles so maintenance is triggered after a preset number of operations:

Retained Variable Initialization Behavior

  • On an Application Start, KAS initializes the retain variables using values stored in non-volatile memory (NVRAM).
  • On an Application Cold Start, KAS initializes the retain variables using their Init values.

Warning - Dependency on Project Compatibility

  • If the declaration of the retain variables is different between the non-volatile memory and the project, the retain variables are also reset to their Init values.

KAS Runtime determines compatibility using:

  • The number of variables of each type.
  • The length of a STRING type variables.

Non-volatile Storage Considerations

  • The non-volatile memory size is hardware dependent.
  • If the size of the retained variables is larger than the non-volatile storage space:
    • An error is logged.
    • Data is not stored in non-volatile memory.
  • See NVRAM.

For the KAS Runtime Simulator, the retained variables are saved in a file in the project repository.

Actions that Reset Retained Values to Init Values

These changes invalidate existing retained data and reset to their Initial values.

  • Change the type of a retain variable.
  • Change the length of a string retain variable.
  • Change the size of an array variable.
  • Change any element of a structure variable.
    • This includes adding new members.

  • Even small structural changes (e.g., adding one field) cause a complete reset of the affected retained variable.

See Also