`lib-control` 库参考

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

导读： 控制引擎扩展

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

目录（导读）

lib
meta
docs
tags
funcs
Overview
Programs
Props
- Prop Types
- Block Props
- Bool Props
- Number Props
- Str Props
- Duration Props
Vars
- Shared Vars
- Bound Vars
- Bundle Vars
- Unlink Mode
Monitoring
XML
bLine Custom Blocks
- def
blocks()
- supertypes
controlTask(program, target)
controlTaskRawVals(program, target)
- src
controlTasks(program: null, target: null)
filterTasksVars(expr)
invokeBlockTaskVariables()
programRead(program)
programTargets(program)
programVarLocs(program)
runRoutine(program, target, routineName)
taskBundle(program, target, varName)
taskDiagram(program, target)
taskGetVarsFor(rec)
taskMonitorPoll(program, target, lastCycle: null)
taskSetMonitorMode(program, target, vars)
taskSetUnlinkMode(program, target, vars)
taskSetVars(program, target, vars)
taskVarTree(target)
taskVarsBoundTo(rec)
taskVarsLinkedTo(program, target, varName)

概述（中译）

控制引擎扩展

API 正文（英文）

docs

Overview • Programs • Props • Vars • Monitoring • XML • bLine Custom Blocks


program	Identifies and defines a control program
programOn	String filter which defines the targets for a control `program`
programRef	Reference to associated `program` rec
programVars	Zinc encoded table of variable definitions

funcs


blocks	List the installed control blocks
controlTask	Get the details for the task identified by the given program and target combination
controlTaskRawVals	Haystack flattens time units to ms (1min -> 60000) Strip the unit from time values so we get the raw number
controlTasks	List the tasks for all the programs currently running
filterTasksVars	Reads all tasks variables that match the filter and return them in a grid
invokeBlockTaskVariables	Get the current Task Variables when the top function was called by the Invoke block
programRead	Given a program id or rec, return a dict of the program with the XML normalized with the addition of `line` attribute on each block element
programTargets	Given a program rec or id, return the a grid with the targets matched by the program's `programOn` filter
programVarLocs	Given a program id, return a table of all the variables and their line number locations in the program definition
runRoutine	Asynchronously run the routine identified by given program, target, and routine name
taskBundle	Read the current state of a bundle variable
taskDiagram	Given task or target rec, return the diagram for all the entity relationships to visualize data sharing
taskGetVarsFor	Given a rec or rec id, find all the variables which are set on that record
taskMonitorPoll	Poll the var monitor table for the task identified by the given program and target
taskSetMonitorMode	Set or clear the monitor mode for a set of variables in the task identified by the given program and target
taskSetUnlinkMode	Set or clear the unlink mode for a set of variables in the task identified by the given program and target
taskSetVars	Manually set the given task variables identified by the given program and target
taskVarTree	Return a grid which defines a tree of potential variables to create for a target rec
taskVarsBoundTo	Given a rec or rec id, find all the task variables which are bound to that rec
taskVarsLinkedTo	Given a task identified by the given program and target and a variable name, return all the other tasks where that variable has shared usage

lib control

Overview

The controlExt implements a control engine based upon the following principles:

programs implement control logic using a tree of blocks
programs are organized into one or more routines
routines are scheduled to run cyclically, on conditions, or manually
programs are registered on targets using the programOn tag
tasks are created for for each unique program and target combition
tasks maintain their state via variables
local variables maintain state on a per task basis
shared variables allow state to be shared between tasks
bound variables allow state to be shared through folio and point writes
bundle variables allow variable tables to be shared between programs

Programs

Programs have the following tags:

name: required programatic name of the program. The name must unique in project (shared with Axon func namespace)
dis: optional display name for the program
program: required Str which defines the XML definition of the program
programOn: required Str which defines the filter used to register the program on targets
programVars: optional tag which defines the program variables as a Zinc string

Props

Blocks are defined by a set of named properties or props. Properties have the following attributes:

name: programatic name of the property
type: type of the property value (see below for types)
additional type specific tags
doc: fandoc encoded description of the property

Prop Types

Standard prop types:

Block: child block
Block[]: list of child blocks (only supported by n-ary blocks)
Bool: boolean value of true/false
Number: numeric value
Str: string value
Duration: as number with duration unit ("ms", "sec", "min", etc)

Block Props

Standard tags for Block and and Block[] properites:

takes: filter for what kind of block is expected (described below)

Many properties define a takes tag which is a string filter describing what is expected for the properties which take a child block. Standard takes tags:

stmt: child block type must be stmt
obj: child block expression that returns any object type
bool: child block must be boolean expression
number: child block must be numeric expression
str: child block must be string expression

Bool Props

Standard tags for Bool props:

defVal: default value for property
enum: comma separated list of "false,true" strings

Number Props

Standard tags for Number props:

defVal: default value for property

Str Props

Standard tags for Str props:

defVal: default value for property
routineName: routine name expected
varName: variable name expected
enum: comma separated list enumerated string values

Duration Props

Standard tags for Duration props:

defVal: default value for property

Vars

The programVars tag stores a docSkySpark::Zinc encoded table of the variable definitions and bindings. Columns of the table:

name: programmatic name of the variable which matches the name used in the block tree
kind: type of variable as kind name, if omitted variable may be any kind
defVal: default value used to initial variable, or null if omitted
ro: the variable is readonly inside the program; attempts to set the variable inside the program logic will raise a ReadonlyErr
shared: creates shared variable with scope of "<proj>" or ref tag name
binding: filter string to bind the variable to a rec Folio database
readTag: binding rec tag to use for reads before execution (typically curVal)
writeTag: binding rec tag to write after execution
writeLevel: number between 1 - 16 to use for pointWrite() after execution
unlinkMode: marker to init the variable in unlink mode
bundle: Str formatted as "programName@refTag" - see bundles

Variable exist one of the following states:

local: this is a variable local to the task during execution, they are maintained in memory between execution cycles
shared: variables shared between multiple tasks using a configured scope
bound: these are variables bound to recs in the Folio database

Shared Vars

Tasks can share a variable's value via the shared tag in the variable table. Shared variables of the same name have visibility based on a configured scope. Typically the scope is defined by a Ref tag on the target bound by the program's programOn tag. Using the "id" tag defines scope based on the target itself. You can also use the special string "<proj>" to define project wide scope.

Let's consider an example:

programOn: ahu
programVars:
  ver:"2.0"
  name,kind,shared
  "projVar","Number","<proj>"
  "siteVar","Number","siteRef"
  "equipVar","Number","id"

The program above is registered on all AHU equip recs. The projVar will be shared across all tasks in the project that declare a shared variable with the same name. The siteVar is shared across all tasks which declare a shared variable name identifying the AHU's site as the scope. The equipVar will be shared across all tasks identifying the AHU equip rec as the shared scope (since the AHU is the target itself).

Bound Vars

Bound variables allow programs to read/write to the Folio database. A variable is bound to a record in Folio using the binding tag. This is a string filter which uses the macro syntax. When a program is loaded for a given a target, the filter macro is evaluated with the macro keys of all the target's Ref tags. Here is an example of a program registered on AHUs which declares three variables for the fan, discharge temp, and return temp:

programOn: ahu
programVars:
  ver:"2.0"
  name,kind,binding,readTag
  "fan","Bool","equipRef==\$id and fan and cmd","curVal"
  "dat","Number","equipRef==\$id and discharge and temp and sensor","curVal"
  "rat","Number","equipRef==\$id and \"return\" and temp and sensor","curVal"
  "siteArea","Number","id==\$siteRef","area"
  "ahuVendor","Str","id==\$id","vendor"

Bound vars work as follows:

bound variables are added to a watch per program
all bound variables are read before task execution
the task is executed
any bound variables which are set during execution are written back to folio/point array

By default, a bound variable is read-only. If you wish to write the variable's value back out to Folio after execution, then use the writeTag to specify which tag to write on the bound rec. This value is always written to Folio using a transient diff. Alternatively you can write the value to a writable point priority array using writeLevel.

Bundle Vars

Bundle variables allow a program to access the variable table of multiple tasks as a grid. A bundle variable is declared with the bundle tag in the variable table using the syntax "programName@refTag". For example consider this scenerio:

// database of AHU and VAV recs
id: @ahu-1, ahu
id: @vav-1A, vav, ahuRef: @ahu-1
id: @vav-1B, vav, ahuRef: @ahu-1
id: @ahu-2, ahu
id: @vav-2A, vav, ahuRef: @ahu-2
id: @vav-2B, vav, ahuRef: @ahu-2

// program on VAVs
name: "vavProgram"
programOn: "vav"
programVars:
  ver:"2.0"
  name
  "roomTemp"
  "damper"

// program on AHUs
name: "ahuProgram"
programOn: "ahu"
programVars:
  ver:"2.0"
  name,bundle
  "vavs","vavProgram@ahuRef"

In the example above the ahuProgram imports all the variables of its associated VAVs into a variable named vavs. This variable will be a grid where the columns are the variables and the rows are the tasks associated to the AHU program target by the ahuRef tag. For example the vavs variable of ahu-1 will be a grid which looks like this:

targetRef,roomTemp,damper
@vav-1A,73°F,34%
@vav-2A,75°F,90%

Notice that the first column identifies the target of the vavProgram task. The rest of the columns represent the variables declared in the vavProgram programVars table (local undefined variables are not included). The rows match the tasks where the vav target has a ahuRef tag that matches the id of the ahu target rec.

Unlink Mode

Individual variables of a task can be set into a special unlink mode. In this mode, neither bound vars or shared vars are read or written outside of the task. This allows the program to be tested without any side effects. Variable unlink mode is controlled via the taskSetUnlinkMode() function.

Monitoring

Variables of a task may be set into monitor mode. During monitor mode, the control engine maintains an internal trend history of the variables for debugging. Each variable in monitor mode has its state captured at the end of a control engine cycle if one or more routines of the task execute. The trend includes the value of the variable and the line number of the last block to set the variable (or null if the variable was not set during the cycle).

The taskSetMonitorMode() function is used to put variables into and out of monitor mode. The taskMonitorPoll() is used to poll the monitored trend. Clients should optimize their polling by passing lastCycle to only read newer trend rows. Monitoring works on a lease model, if a client fails to poll after 1min then the task's monitoring is disabled and cleared.

XML

The program tag stores the XML encoding of the block tree. Each XML element maps to one block. The following rules are used:

non-const blocks are encoded with element <b>
const blocks are encoded with element <c>
prop name is encoded with p attribute if the block is a named child
block definition type is encoded with t attribute
all other attributes map to scalar (non-block) prop values

Const blocks are encoded using the special representation of <c>val</c> where the value is encoded according to the scalar's docSkySpark::Zinc representation. If the const block is a named child prop, then it may also support the p attribute.

Children blocks may be named or unnamed. If the block supports an arity of "unary", "binary", or "n" then its children blocks may be left unnamed (no p attribute). All other compound blocks must identify the child prop name using the p attribute.

Examples:

<c>T</c>         // const Bool
<c>74°F</c>      // const Number
<c>"string"</c>  // const Str

// unary negate 7
<b t='neg'>
  <c>7</c>
</b>

// binary 4 - 3
<b t='sub'>
  <c>4</c>
  <c>3</c>
</b>

// n-ary block
<b t='add'>
  <c>5</c>
  <c>6</c>
  <c>7</c>
</b>

// compound block with named children
<b t='if'>
  <c p='cond'>T</c>
  <b p='then' t='set' name='result'><c>"is true!"</c></b>
  <b p='then' t='set' name='result'><c>"is false!"</c></b>
</b>

bLine Custom Blocks

Custom blocks can be created with a JavaScript-style language.

Examples:

//bLine Custom Blocks

//Setting a value:
a = 2;
a = b;

//Adding two values:
a = b + 2;

//More aritmetical operations:
a = c * ( a - 3) + a / 10;

//Logical "and":
a = b && c;

//Logical "or":
a = b || c;

//Logical "not":
a = !b;

//capture all variables inside a variables
foo = varCapture();

//access a property
a = foo.mad;

//calling a builtin routine/block
a = now();

//use double quotes to declare a string value
a = "Some text here";

//sending an email
email("email@example.com", "My Subject", "Email Text");

//to add units to a numberic value, enclose them both into single quotes:
wait('10sec');

//If the single quoted value contains a space, then it's considered a string:
//This is a string:
a = 'has space';

//If the single quoted value does not starts with a digit, then it's cosidered a string:
//This is a string:
a = 'text10';

//Back quotes work just like double quotes, but they can be multiline strings:
a = `This is
my multiline string`;

//This could have been done with double quotes or single quotes using \n:
a = "This is\nmy multiline string";
a = 'This is\nmy multiline string';

//Using an if/else:
if (temp > 10) {
   foo = 10;
}
else {
   foo = 20;
}

//adding an alarm block
alarmBlock(variableName, 
           {alarmText:"alarm text", 
            instructions:"alarm instruction", 
            priority:2, 
            cost:1, 
            tag10: true, 
            foo20: 21, 
            marker1});

//call axon function by writing an underscore before there namespace
_myAdd(2, 3)   //calls an axon function named myAdd


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


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


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


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

lib-control 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

funcs ​

lib control ​

Overview ​

Programs ​

Props ​

Prop Types ​

Block Props ​

Bool Props ​

Number Props ​

Str Props ​

Duration Props ​

Vars ​

Shared Vars ​

Bound Vars ​

Bundle Vars ​

Unlink Mode ​

Monitoring ​

XML ​

bLine Custom Blocks ​

func:blocks ​

blocks() ​

func:controlTask ​

controlTask(program, target) ​

func:controlTaskRawVals ​

controlTaskRawVals(program, target) ​

src ​

func:controlTasks ​

controlTasks(program: null, target: null) ​

func:filterTasksVars ​

filterTasksVars(expr) ​

func:invokeBlockTaskVariables ​

invokeBlockTaskVariables() ​

func:programRead ​

programRead(program) ​

func:programTargets ​

programTargets(program) ​

func:programVarLocs ​

programVarLocs(program) ​

func:runRoutine ​

runRoutine(program, target, routineName) ​

func:taskBundle ​

taskBundle(program, target, varName) ​

func:taskDiagram ​

taskDiagram(program, target) ​

func:taskGetVarsFor ​

taskGetVarsFor(rec) ​

func:taskMonitorPoll ​

taskMonitorPoll(program, target, lastCycle: null) ​

func:taskSetMonitorMode ​

taskSetMonitorMode(program, target, vars) ​

func:taskSetUnlinkMode ​

taskSetUnlinkMode(program, target, vars) ​

func:taskSetVars ​

taskSetVars(program, target, vars) ​

func:taskVarTree ​

taskVarTree(target) ​

func:taskVarsBoundTo ​

taskVarsBoundTo(rec) ​

func:taskVarsLinkedTo ​

taskVarsLinkedTo(program, target, varName) ​

program ​

programOn ​

programRef ​

programVars ​

`lib-control` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

funcs

lib control

Overview

Programs

Props

Prop Types

Block Props

Bool Props

Number Props

Str Props

Duration Props

Vars

Shared Vars

Bound Vars

Bundle Vars

Unlink Mode

Monitoring

XML

bLine Custom Blocks

func:blocks

blocks()

func:controlTask

controlTask(program, target)

func:controlTaskRawVals

controlTaskRawVals(program, target)

src

func:controlTasks

controlTasks(program: null, target: null)

func:filterTasksVars

filterTasksVars(expr)

func:invokeBlockTaskVariables

invokeBlockTaskVariables()

func:programRead

programRead(program)

func:programTargets

programTargets(program)

func:programVarLocs

programVarLocs(program)

func:runRoutine

runRoutine(program, target, routineName)

func:taskBundle

taskBundle(program, target, varName)

func:taskDiagram

taskDiagram(program, target)

func:taskGetVarsFor

taskGetVarsFor(rec)

func:taskMonitorPoll

taskMonitorPoll(program, target, lastCycle: null)

func:taskSetMonitorMode

taskSetMonitorMode(program, target, vars)

func:taskSetUnlinkMode

taskSetUnlinkMode(program, target, vars)

func:taskSetVars

taskSetVars(program, target, vars)

func:taskVarTree

taskVarTree(target)

func:taskVarsBoundTo

taskVarsBoundTo(rec)

func:taskVarsLinkedTo

taskVarsLinkedTo(program, target, varName)

program

programOn

programRef

programVars