Remanent Variables - PERSISTENT, RETAIN

Remanent variables can retain their values beyond the usual program runtime. Remanent variables can be declared as RETAIN variables or even more strictly as PERSISTENT variables in the PLC project.

A prerequisite for the full functionality of RETAIN variables is a corresponding memory area on the controller (NovRam). Persistent variables are written only when TwinCAT shuts down. This will require usually a corresponding UPS. Exception: Persistent variables can also be written with the FB_WritePersistentData function block.

If the corresponding memory area does not exist, the values of RETAIN and PERSISTENT variables are lost during a power failure.

Remanent Variables - PERSISTENT, RETAIN 1:

The AT declaration must not be used in combination with VAR RETAIN or VAR PERSISTENT.

Persistent Variables

You can declare persistent variables by adding the keyword PERSISTENT after the keyword for the variable type (VAR, VAR_GLOBAL, etc.) in the declaration part of programming objects.

PERSISTENT variables retain their value after an uncontrolled termination, a Reset cold or a new download of the PLC project.
When the program restarts, the system continues to operate with the stored values. In this case TwinCAT reinitializes "normal" variables with their explicitly specified initial values or with the default initializations.
In other words, TwinCAT only reinitializes PERSISTENT variables during a Reset origin.

An application example for persistent variables is an operating hour counter, which is to continue counting after a power failure and when the PLC project is downloaded again.

Overview table showing the behavior of PERSISTENT variables

After online command

VAR PERSISTENT

Reset cold

Values are retained

Reset origin

Values are reinitialized

Download

Values are retained

Online Change

Values are retained

Sample:

Persistent variable list:

VAR_GLOBAL PERSISTENT
    nVarPers1 : DINT; (* 1. Persistent variable *)
    bVarPers2 : BOOL; (* 2. Persistent variable *)
END_VAR
Remanent Variables - PERSISTENT, RETAIN 2:
  • Avoid using the POINTER TO data type in persistent variable lists, since the address values ​​may change when the PLC project is downloaded again! TwinCAT issues corresponding compiler warnings.
  • Declaring a local variable as a PERSISTENT in a function has no effect. Data persistence cannot be used in this way.
  • The behavior during a cold reset can be influenced with the pragma 'TcInitOnReset'

RETAIN variables

You can declare RETAIN variables by adding the keyword RETAIN after the keyword for the variable type (VAR, VAR_GLOBAL, etc.) in the declaration part of programming objects.

Variables declared as RETAIN are target system-dependent, but typically managed in a separate memory area that must be protected against power failure. The so-called Retain handler ensures that the RETAIN variables are written at the end of a PLC cycle and only in the corresponding area of the NovRam. The handling of the retain handler is described in chapter "Retain data" of the C/C++ documentation.

RETAIN variables retain their value after an uncontrolled termination (power failure). When the program restarts, the system continues to operate with the stored values. In this case TwinCAT reinitializes "normal" variables with their explicitly specified initial values or with the default initializations.
TwinCAT reinitializes RETAIN variables at a reset origin.

One possible application is a part counter in a production plant, which should continue to count after a power failure.

Overview table showing the behavior of RETAIN variables

After online command

VAR RETAIN

Reset cold

Values are retained

Reset origin

Values are reinitialized

Download

Values are retained

Samples:

In a POU:

VAR RETAIN
    nRem1 : INT;
END_VAR

In a GVL:

VAR_GLOBAL RETAIN
    nVarRem1 : INT;
END_VAR
Remanent Variables - PERSISTENT, RETAIN 3:
  • If you declare a local variable as a RETAIN in a program or a function block, TwinCAT stores this specific variable in the retain area (like a global RETAIN variable).
  • If you declare a local variable in a function as RETAIN, this has no effect. TwinCAT does not store the variable in the retain area.

Complete overview table

The degree of retention of RETAIN variables is automatically included in that of PERSISTENT variables.

After online command

VAR

VAR RETAIN

VAR PERSISTENT

Reset cold

Values are reinitialized

Values are retained

Values are retained

Reset origin

Values are reinitialized

Values are reinitialized

Values are reinitialized

Download

Values are reinitialized

Values are retained

Values are retained

Online Change

Values are retained

Values are retained

Values are retained

See also: