Retain Variables

What is a retain variable?

A retain variable is a PLC variable which:

  • is non-volatile: stored in non-volatile controller memory (AKD PDMM or PCMM). When using 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 is started the retained values are used. Additionally, retains are auto-saved every two seconds. This applies to both the AKD PDMM and PCMM models.
    • Variables stored in non-volatile memory that have changed will be updated every two seconds. Unchanged variables are not updated.

Such a variable is used to store application specific data, like for instance to count a cutting-edge cycle in order to stop for its blade replacement after a specific number of iterations.

  • On an application “Start”, KAS initializes the retain variables with the value stored in the NVRAM.
  • On an application “Cold Start”, KAS initializes the retain variables with their default value.
  • 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 default value.

Two parameters are checked to identify if the declaration changed:

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

  • 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 will be logged and the data will not be stored in non-volatile memory. See NVRAM for more information.

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


  • The following actions will reset retained value(s) to their Init value(s):

    • Changing the type of a retain variable
    • Changing the length of a string retain variable
    • Changing the size of an array variable
    • Changing any element of a structure variable

  • Retained variables should not be used as the output of Function Blocks.

    Doing so may cause problems with retaining the value if the FB is executed with the Enable input off.
    The output structure can cause it to be conditionally updated to zero or the old value.

    A work-around solution is to use a copy (1 gain) function to selectively enable updating the retain variable from an intermediate variable, which is the output of a function block.

    In this image:

    • The ReadActualPositionX is continually reading position feedback from an axis.
      • The copy block is saving a specific value to a retain variable.
    • ActualPositionX is the intermediate variable and SavedPositionX is the retain variable.

Copy a Retained Variable Value to Init Value

Once determined, retained variable values can be saved to the variable's initial value.

This allows for the KAS project to more easily be re-used for other, similar machines.

This example determines a retain variable's value and saves the value to the retain variable's initial value.

  1. Run the program to determine the retain variable's value, which is FALSE.

  2. Right-click the variable and select Copy variable value to init value.

  3. The Init value field is now "FALSE".

Limitations

The copy function has several limitations

  • The menu item is only enabled under these conditions:
    • The project must be compiled and running, and the KAS-IDE is connected to the controller.
    • One or more retain variables must be selected (an individual variable or a group).
  • The program must be recompiled and downloaded for this to take effect.
  • Arrays and structures are not supported.