Glossary · PLC and control programming
Retain variable
Also known as: Retentive variable
German: Retain-Variable
In IEC 61131-3 programming, a retain variable is a variable declared with the RETAIN qualifier, whose value is kept through a power failure and a warm restart of the controller.
- PLC programming
- Standards
In one sentence
A retain variable (RETAIN) keeps its value through a power failure and warm restart, for example counters or settings.
Example
The operating hours counter of a compressor is declared as a retain variable, so it continues counting after the machine has been switched off.
How it applies
- Engineering: Retain variables hold values that must survive power loss: counters, calibration offsets, settings, production data. IEC 61131-3 defines RETAIN and NON_RETAIN qualifiers; controllers additionally offer PERSISTENT or similar options that also survive program downloads, with vendor-specific rules.
- Behavior: A warm restart keeps retain values; a cold restart or reset typically initializes them. Exact behavior depends on the controller, and retentive memory size is limited.
- Safety: Retaining commands or sequence states can make a machine resume unexpectedly after power returns. Only values whose retention is safe and intended should be retentive.
- Documentation: List retentive values in the software documentation and describe how to back them up before a CPU replacement or firmware update. The operating manual should say which settings survive a power failure.
Retain variable vs. retentive memory
A retain variable is a declaration in the program. Retentive memory is the controller's memory area that makes retention possible. The declaration places the variable into that memory.