system.tag

system.tag is a script's way to the tag system: live values, writes, what a tag is, what sits under a folder, and stored history. Every kind of script has read; the rest need a context that may call the gateway (screen, cron, console, module). See The system API for how calls run and fail.

Types

type ScadexQuality = "good" | "uncertain" | "bad";

interface ScadexTagReading<V = unknown> {
  path: string;
  value: V | null;
  quality: ScadexQuality;
  timestamp: number | null;   // epoch milliseconds
}

interface ScadexTagInfo {
  path: string;
  name: string;
  kind: string;               // memory, opcua, mqtt, external, derived, expression, udt, folder, udt-type, system
  dataType: string | null;    // Boolean, Int32, UInt32, Int64, UInt64, Float, Double, String, DateTime, Dataset; null for a folder
  enabled: boolean;
  description: string;
  unit: string;               // "" when none
  hasChildren: boolean;
}

interface ScadexHistoryPoint<V = unknown> {
  t: number;                  // epoch milliseconds
  v: V | null;
  quality: ScadexQuality;
}

TagPath is any tag path; the editor types a path it knows from the tag list, and leaves one it cannot know as any.

Reading and writing

read

read<P extends TagPath>(path: P): TagValue<P>

The tag's live value in engineering units; the same as the global tag(path). Runs inside the script. In a screen or cron script a path not yet seen is read from the gateway (at most 256 distinct tags per script); in an expression tag only the expression's literal inputs have values and any other path is undefined. Returns undefined for a tag that does not exist.

reading

reading<P extends TagPath>(path: P): ScadexTagReading<TagValue<P>>

Parameter	Type	Meaning
path	string	The tag's path. Required

Returns the value with its quality and time. For a path with no current value, value is null, quality is "bad" and timestamp is null. A @gateway diagnostic tag answers with quality: "good" and the time of the call. Gateway call; any role.

var r = system.tag.reading('Plant.Tank1.Level');
if (r.quality !== 'good') return { toast: { message: 'Level is ' + r.quality, variant: 'warning' } };

write

write<P extends TagPath>(path: P, value: TagValue<P>): void

Asks for a write, like the global writeTag(path, value). Writes are applied in order after the script has finished, stopping at the first that fails; a script that fails writes nothing. At most 64 writes per script. A screen script needs the operator role for its writes to be applied; a cron script writes as cron:<job name>. In an expression tag it throws system.tag.write: an expression tag can't write tags.

Describing tags

exists

exists(path: string): boolean

Whether a tag exists at this path. Gateway call; any role.

info

info(path: TagPath): ScadexTagInfo | null

What the tag is: its kind, data type, unit, description (the tag's tooltip, or the first line of its documentation) and whether it holds other tags. null when there is none at this path. A @gateway tag answers with kind: "system" and no data type. Gateway call; any role.

browse

browse(path?: TagPath): ScadexTagInfo[]

Parameter	Type	Meaning
path	string	A folder or instance. Leave it out for the top level

The tags directly under path, ordered by path, at most 10,000. Tag types under @types are left out. Gateway call; any role.

var motors = system.tag.browse('Line1').filter(function (t) { return t.kind === 'udt'; });
console.log(motors.map(function (t) { return t.name; }).join(', '));

History

history

history<P extends TagPath>(path: P, options: { from: ScadexTime; to?: ScadexTime; maxPoints?: number }): ScadexHistoryPoint<TagValue<P>>[]

Parameter	Type	Meaning
path	string	The tag. Required
options.from	Date, epoch ms or ISO 8601	Where the history starts. Required
options.to	time	Where it ends; now when left out. Must not be before from
options.maxPoints	number	At most this many points; 1,000 when left out, clamped to 1 to 10,000

Stored values between the two moments, oldest first, with each point's quality. The points come from the same source as a replay (see History and replay), so a tag without history returns an empty list. Gateway call; any role.

Errors: options.from is required: when the history starts., options.to is before options.from.

var since = system.date.addHours(system.date.now(), -1);
var points = system.tag.history('Plant.Tank1.Level', { from: since, maxPoints: 500 });
var max = points.reduce(function (m, p) { return p.v !== null && p.v > m ? p.v : m; }, -Infinity);
return { points: points.length, max: max };