Writing your own function

The problem: the same equation in twenty places

On a station with twenty analogue transmitters you copy this line twenty times with different numbers:

Flow := (RawFlow - 4.0) / 16.0 * 250.0;
Pres := (RawPres - 4.0) / 16.0 * 10.0;

In one of them you type 16.0 where 4.0 belonged, a reading is wrong, and you spend three days finding it. The fix is to write the equation once, in a function.

Declaring one

FUNCTION Scale4to20 : REAL
VAR_INPUT
  Raw   : REAL;   (* 4.0 .. 20.0 mA *)
  EngLo : REAL;
  EngHi : REAL;
END_VAR

Scale4to20 := EngLo + (Raw - 4.0) / 16.0 * (EngHi - EngLo);

END_FUNCTION

Three things to notice:

1. The type follows the name: FUNCTION Scale4to20 : REAL means it returns a REAL.
2. Inputs live in VAR_INPUT: read-only inside the body.
3. You return by assigning to the function's own name: Scale4to20 := .... That is the standard syntax; there is no return keyword.

Calling it

Flow := Scale4to20(RawFlow, 0.0, 250.0);
Pres := Scale4to20(RawPres, 0.0, 10.0);
Temp := Scale4to20(RawTemp, -50.0, 200.0);

Or by name, which reads better in review:

Flow := Scale4to20(Raw := RawFlow, EngLo := 0.0, EngHi := 250.0);

Purity: no memory, no side effects

A function is pure: the same inputs always give the same result, and nothing is remembered between calls. That means:

• No timers and no counters inside it. A TON needs memory, so it belongs in a FUNCTION_BLOCK.
• Local VAR values inside a function are undefined at the start of each call. Never rely on them.
• Do not write to a global from inside a function. Some platforms let you, but it makes the result depend on the program's history, which is exactly what you were avoiding.

When do you need a FUNCTION_BLOCK instead? When the answer to "does it need to remember anything from the previous scan?" is yes.

Functions worth writing

• Scale4to20 and ScaleRaw: engineering-unit conversion.
• DeadbandPct: a deadband around a setpoint.
• CelsiusToF, BarToPsi: unit conversion.
• ClampPct: hold a value between 0 and 100 and flag the overshoot.

Each is reviewed once, tested once, and correct everywhere after that.

Not runnable in the lab

The lab on this site runs a single PROGRAM and does not support declaring a FUNCTION. The examples above are code to read, not to run. The lab program below does the same maths inline so you can watch the numbers move.