# RTOR — Retentive Timer

Source: https://rungs.dev/docs/structured-text/instructions/rtor

> RTOR is the Structured Text retentive timer function block in rungs.dev. It uses FBD_TIMER and mirrors the behavior of the ladder RTO instruction.

Structured Text retentive timer function block. Uses `FBD_TIMER`; the ST equivalent of ladder [`RTO`](https://rungs.dev/docs/ladder-logic/instructions/rto).

## Operands [#operands]

| Name    | Type        |
| ------- | ----------- |
| `timer` | `FBD_TIMER` |

## `FBD_TIMER` Tag Members [#fbd_timer-tag-members]

| Member           | Type   | Meaning                                                                        |
| ---------------- | ------ | ------------------------------------------------------------------------------ |
| `.EnableIn`      | `BOOL` | Forced to `1` each scan by the instruction call — setting it `0` has no effect |
| `.TimerEnable`   | `BOOL` | `1` runs the timer and advances `ACC`; `0` stops timing                        |
| `.PRE`           | `DINT` | Preset target time in milliseconds                                             |
| `.Reset`         | `BOOL` | `1` clears `EN`, `TT`, `DN` and sets `ACC` to `0`                              |
| `.EnableOut`     | `BOOL` | `1` while the instruction is executing normally                                |
| `.ACC`           | `DINT` | Accumulated time in milliseconds                                               |
| `.EN`            | `BOOL` | `1` while `TimerEnable` is `1` and `Reset` is `0`                              |
| `.TT`            | `BOOL` | `1` while the timer is actively counting toward `PRE`                          |
| `.DN`            | `BOOL` | Done status — each timer (`TONR`, `TOFR`, `RTOR`) decides when this turns on   |
| `.Status`        | `DINT` | Packed status word — combines `InstructFault` and `PresetInv` bits             |
| `.InstructFault` | `BOOL` | `1` when the instruction hit an execution error                                |
| `.PresetInv`     | `BOOL` | `1` when `PRE` is outside its valid range                                      |

## How It Works [#how-it-works]

`RTOR` is the Structured Text function-block equivalent of the ladder [`RTO`](https://rungs.dev/docs/ladder-logic/instructions/rto) instruction. It operates on an `FBD_TIMER` tag.

Like `TONR`, but `.ACC` retains its value when `TimerEnable` drops to `0`. Timing resumes where it left off. Clear the accumulator by setting `.Reset` to `1`.

## Example [#example]

```iecst
RunHours.TimerEnable := MachineRunning;
RunHours.Reset := ResetMaint;
RunHours.PRE := 28800000;
RTOR(RunHours);

MaintAlert := RunHours.DN;
```

> **IDEA**
>
> **Practice**
>
> Try `RTOR` in the [Run Hours exercise](https://rungs.dev/exercises/run-hours) — accumulate a motor's run time and retain it across enable drops.

## Common Mistakes [#common-mistakes]

- Trying to pause with `.EnableIn := 0`. The instruction call forces `.EnableIn` back to `1` every scan, so the assignment has no effect. To pause and keep `.ACC`, drop `.TimerEnable` to `0`; clear the accumulator with `.Reset`.
- Assigning `.ACC` from logic to reset it (`MyTimer.ACC := 0`). Structured Text recomputes `.ACC` every scan, so a runtime write is **ignored** (the initial `.ACC` default is still honored). Clear it with `.Reset := 1`. The same write _does_ take effect on the ladder [`RTO`](https://rungs.dev/docs/ladder-logic/instructions/rto) — so don't rely on it either way; it isn't portable.

## Related [#related]

- [RTO](https://rungs.dev/docs/ladder-logic/instructions/rto) — the ladder-logic equivalent
- [TONR](https://rungs.dev/docs/structured-text/instructions/tonr), [TOFR](https://rungs.dev/docs/structured-text/instructions/tofr) — other ST timer function blocks