system.util
system.util holds small helpers. They run inside the script's own engine, cost no gateway call, and are available in every kind of script, including expression tags. See The system API for the rest of system.
uuid
uuid(): string
A new random id in the UUID form xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx, made from Math.random. It is unique enough to name a record or a correlation; it is not a cryptographic token.
system.db.update('INSERT INTO batches (id, started_at) VALUES (?, ?)', [system.util.uuid(), system.date.now()]);
jsonEncode
jsonEncode(value: unknown, pretty?: boolean): string
| Parameter | Type | Meaning |
|---|---|---|
value | any | What to encode. Required |
pretty | boolean | Indent with two spaces |
JSON.stringify(value), indented when pretty is true. A Date becomes its ISO text; undefined, functions and cyclic objects follow JavaScript's rules (left out, or an error for a cycle).
jsonDecode
jsonDecode<T = unknown>(text: string): T
JSON.parse(text). Text that is not JSON throws a SyntaxError, which fails the script unless caught. The type parameter only tells the editor what to expect; nothing is checked at run time.
var config = system.util.jsonDecode(tag('Line1.Recipe')); // a String tag holding JSON
writeTag('Line1.Setpoint', config.setpoint);
clamp
clamp(value: number, low: number, high: number): number
The number kept between low and high: Math.min(high, Math.max(low, value)).
writeTag('Line1.Speed', system.util.clamp(Number(val), 0, 1500));
round
round(value: number, decimals?: number): number
| Parameter | Type | Meaning |
|---|---|---|
value | number | The number. Required |
decimals | number | Places to keep; 0 when left out |
Math.round(value * 10^decimals) / 10^decimals, so halves round up (round(2.5) is 3, round(-2.5) is -2) and a result of n decimals may still carry floating-point noise where the number has no exact binary form.
return system.util.round(tag('PLC.AI.Flow_Raw') * 100 / 27648, 1);