`lib-finWatcher` 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793259265/FIN+5.3.1+lib-finWatcher 中文整理基于 FIN 5.3.1

导读： FIN观察者扩展

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

lib
meta
docs
tags
funcs
Overview
- def
- supertypes
finResetBoolStats(ops: Etc.makeDict(["runStarts","runTime"]))
finResetStatsStartTime(points: null, ts: null)
finWatcherCallbackOn(filter, chagedRefs: Etc.makeEmptyGrid())
standardFinWatcher(self, ts)
- src

概述（中译）

FIN观察者扩展

API 正文（英文）

docs

Overview


finBoolStatsFreq	Tune how often the FinWatcher computes boolean `runStarts` and `runTime`
finWatcherAdded	Marker tag for an added record
finWatcherCallback	Marker tag for a callback function that instructs the watcher to call it when changes are detected
finWatcherCallbackOn	Axon expression tag placed on a `finWatcherCallback` callback
finWatcherChanged	Marker tag for a changed record
finWatcherChangedRef	Reference to the record that is detected as changed
finWatcherChanges	A serialized Zinc grid that encodes which tags where added/changed/removed on a `finWatcherChangedRef` record
finWatcherFreq	Tune how often the FinWatcher looks for changes
finWatcherRemoved	Marker tag for a removed record
statsResetTs	Set the start time used to calculate the statistics

funcs


finResetBoolStats	Resets runtime statistics for bool points By default this will reset both `runStarts` and `runTime`
finResetStatsStartTime	Resets the start time from when boolean statistics are collected
finWatcherCallbackOn	Based on the filter expression, returns a grid with all the changes that match the filter expression
standardFinWatcher	standardFinWatcher An example callback function that gets executed by the FinWatcher A callback function is a `func` marked record that has a valid Axon `src` tag

lib finWatcher

Overview

The FinWatcher extension implements a watch mechanism for detecting changes on equipments and also for collecting statistics on historized boolean points.

Each change detected creates a transient record containing:

a finWatcherChangedRef Ref that points to the record that changed
a marker tag for kind of change, finWatcherAdded, finWatcherChanged, finWatcherRemoved
if a change in the record structure is detected, marked as finWatcherChanged, then a finWatcherChanges must be present

The FinWatcher will call a function (func) marked with finWatcherCallback each time a change was detected. There can be multiple callback functions that get executed on a detection pass. The callback function must take 2 parameters, "self" that points to current callback function record id and a "timestamp" (Number) of the last change detected. Functions will take care of selecting what needs to be done with the detected changes and can use the timestamp parameter to process only newer changes. Adding finWatcherCallbackOn tag to a finWatcherCallback function, instructs the FinWatcher to only evaluate the callback function for changes that match the Axon expression inside the finWatcherCallbackOn tag. Change records older than current time - 2x finWatcherFreq will be marked as trash.

The statistic collector for boolean points collects data about how often a point has been in the true states and for how long for a period of time. Each history enabled boolean point will have 2 additional tags for those two values called "runStarts" and "runTime". The initial period is determined by the start date time of the history of that point, then as the stats run, the period's start is the last collector's end date time. The statsResetTs tag can override the start time of the time span the collector uses.

def

finBoolStatsFreq

Tune how often the FinWatcher computes boolean runStarts and runTime. If not configured it defaults to 1h. The value must be greater than 5 seconds

meta


def	finBoolStatsFreq
is	number
lib	lib:finWatcher

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit

def

finWatcherAdded

Marker tag for an added record.

meta


def	finWatcherAdded
is	marker
lib	lib:finWatcher

supertypes


marker	Marker labels a dict with typing information

def

finWatcherCallback

Marker tag for a callback function that instructs the watcher to call it when changes are detected.

meta


def	finWatcherCallback
is	marker
lib	lib:finWatcher

supertypes


marker	Marker labels a dict with typing information

def

finWatcherCallbackOn

Axon expression tag placed on a finWatcherCallback callback. FinWatcher evaluates it to determine if the function can be called for the changes detected.

meta


def	finWatcherCallbackOn
is	str
lib	lib:finWatcher

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

def

finWatcherChanged

Marker tag for a changed record.

meta


def	finWatcherChanged
is	marker
lib	lib:finWatcher

supertypes


marker	Marker labels a dict with typing information

def

finWatcherChangedRef

Reference to the record that is detected as changed.

meta


def	finWatcherChangedRef
is	ref
lib	lib:finWatcher

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
ref	Reference to an entity

def

finWatcherChanges

A serialized Zinc grid that encodes which tags where added/changed/removed on a finWatcherChangedRef record

meta


def	finWatcherChanges
is	str
lib	lib:finWatcher

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

def

finWatcherFreq

Tune how often the FinWatcher looks for changes. If not configured it defaults to 49sec.

meta


def	finWatcherFreq
is	number
lib	lib:finWatcher

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit

def

finWatcherRemoved

Marker tag for a removed record.

meta


def	finWatcherRemoved
is	marker
lib	lib:finWatcher

supertypes


marker	Marker labels a dict with typing information

def

func:finResetBoolStats

finResetBoolStats(ops: Etc.makeDict(["runStarts","runTime"]))

Resets runtime statistics for bool points

By default this will reset both runStarts and runTime.

Users can reset only one of them by setting the tag parameter like:

finResetBoolStats({runTime}) or finResetBoolStats({runStarts})

meta


def	func:finResetBoolStats
is	func
lib	lib:finWatcher
name	finResetBoolStats

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:finResetStatsStartTime

finResetStatsStartTime(points: null, ts: null)

Resets the start time from when boolean statistics are collected. there are 2 optional parameters:

point can be a point or list of points which need to be reseted, if null then all the bools stats point
time stamp, the datetime of the new stats collecting start, if null it is the current datetime

meta


def	func:finResetStatsStartTime
is	func
lib	lib:finWatcher
name	finResetStatsStartTime

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:finWatcherCallbackOn

finWatcherCallbackOn(filter, chagedRefs: Etc.makeEmptyGrid())

Based on the filter expression, returns a grid with all the changes that match the filter expression.

meta


def	func:finWatcherCallbackOn
is	func
lib	lib:finWatcher
name	finWatcherCallbackOn

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:standardFinWatcher

standardFinWatcher(self, ts)

standardFinWatcher An example callback function that gets executed by the FinWatcher A callback function is a func marked record that has a valid Axon src tag. The function is called by the FinWatcher with 2 arguments

self : the calback function record id
ts : last timestamp a change was registered

meta


def	func:standardFinWatcher
dis	standardFinWatcher
finWatcherCallback	✓
finWatcherCallbackOn	vavMyTest == marker()
is	func
lib	lib:finWatcher
name	standardFinWatcher

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

src

(self, ts) => do
    echo("Executing " + self->name)
     // only changed records
    if(self.toRec.has("finWatcherCallbackOn"))
      changes: finWatcherCallbackOn(self->finWatcherCallbackOn)
    else
      return null
    changes.each r => do
        // the record has a payload zip file stored
        f: finReadZipRes(`/pod/finWatcherExt/res/finWatcher/payload.zip`)
        // read the equip tags from the payload
        tags: f.finReadStrZipEntry("/equipTags.trio").ioReadTrio

        // determine what tags need to be added to the changed records
        changes: {}
        // add the tags from `equipTags.trio`
        rec: r->finWatcherChangedRef.toRec
        tags.each tr => do
          tr.each( (v,n) => do
            if(not rec.has(n)) do
              change:  {}
              if(changes.has(rec->id.toStr))
                change = changes.get(rec->id.toStr)
              change = change.set(n, v)
              changes = changes.set(rec->id.toStr, change)
            end
          end)
        end
        // commit the new amended records if any
        diffs: []
        changes.each ((v, n) => diffs = diffs.add(diff(n.parseRef.readById, v )))
        if(not diffs.isEmpty)
          commit(diffs)

        // add the missing program
        programs: f.finReadStrZipEntry("/programs.bline").ioReadZinc
        programs = programs.findAll r => r.has("program")
        programs.each p => do
          if(read(program and name == p->name, false) == null)
            diff(null, p, {add}).commit
        end
        // add the missing points
        points: f.finReadStrZipEntry("/Vav_Clg_Only.trio").ioReadTrio
        points = points.findAll p => p.has("point") and p.has("navName")

        points = points.findAll p => do
          read(point and navName == p->navName and equipRef == rec->id, false) == null
        end
        if(points.isEmpty)
          return null
        points = points.map p => do
         p = p.set("siteRef", rec["siteRef"])
          .set("equipRef", rec->id)
         if(rec.has("floorRef"))
          p = p.set("floorRef", rec["floorRef"])
         p = p.remove("id").remove("mod")
         return p
        end

        points = points.toRecList.map p => diff(null, p, {add})
        if(not points.isEmpty)
          commit(points)
    end
 end

def

statsResetTs

Set the start time used to calculate the statistics.

meta


def	statsResetTs
is	dateTime
lib	lib:finWatcher

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
dateTime	ISO 8601 timestamp followed by timezone identifier

lib-finWatcher 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

funcs ​

lib finWatcher ​

Overview ​

finBoolStatsFreq ​

finWatcherAdded ​

finWatcherCallback ​

finWatcherCallbackOn ​

finWatcherChanged ​

finWatcherChangedRef ​

finWatcherChanges ​

finWatcherFreq ​

finWatcherRemoved ​

func:finResetBoolStats ​

finResetBoolStats(ops: Etc.makeDict(["runStarts","runTime"])) ​

func:finResetStatsStartTime ​

finResetStatsStartTime(points: null, ts: null) ​

func:finWatcherCallbackOn ​

finWatcherCallbackOn(filter, chagedRefs: Etc.makeEmptyGrid()) ​

func:standardFinWatcher ​

standardFinWatcher(self, ts) ​

src ​

statsResetTs ​

`lib-finWatcher` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

funcs

lib finWatcher

Overview

finBoolStatsFreq

finWatcherAdded

finWatcherCallback

finWatcherCallbackOn

finWatcherChanged

finWatcherChangedRef

finWatcherChanges

finWatcherFreq

finWatcherRemoved

func:finResetBoolStats

finResetBoolStats(ops: Etc.makeDict(["runStarts","runTime"]))

func:finResetStatsStartTime

finResetStatsStartTime(points: null, ts: null)

func:finWatcherCallbackOn

finWatcherCallbackOn(filter, chagedRefs: Etc.makeEmptyGrid())

func:standardFinWatcher

standardFinWatcher(self, ts)

src

statsResetTs