`lib-schedule` 库参考

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

导读： 日程安排和日历

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

目录（导读）

lib
meta
docs
tags
apps
funcs
views
def
supertypes
usage
tags
Overview
Calendar
Schedule
Schedulable
scheduleHis(scheduleRec, dates, opts: {}, yield: null)
scheduleSync(timeout: null)
scheduleValAt(scheduleRec, ts)
- src

概述（中译）

日程安排和日历

API 正文（英文）

docs

Overview • Calendar • Schedule • Schedulable


calendar	Marker tag for a calendar entity
calendarGrid	Configures the items for a daily calendar
calendarRef	Used to chain a calendar to a schedule or another calendar
nextTime	Next time stamp when the schedule transition
nextVal	Next value the schedule will transition to
schedulable	Binds a `schedule` to a writable point
schedule	Marker tag for a schedule entity
scheduleGrid	Configures the items for a schedule
scheduleRef	Associates a `schedulable` with its schedule
scheduleVal	The string name/encoding of a schedule value

apps


schedule	Views used to manage schedules

funcs


scheduleHis	Compute a historical or future timeline of a schedule record
scheduleSync	Block until any schedule changes are refreshed
scheduleValAt	Return the scheduled value at the given timestamp

views


schedule	Fresco UI view

app:schedule

Views used to manage schedules

meta


def	app:schedule
disKey	ui::schedule
icon	calendar
is	app
lib	lib:schedule

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
app	UI application grouping of views

calendar

Marker tag for a calendar entity.

meta


def	calendar
is	point
lib	lib:schedule

usage


calendar point

supertypes


marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator


calendarGrid	Configures the items for a daily calendar
cur	Supports current value
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
his	Supports historization of data
id	Defines the unique identifier of an entity in system using a `ref` value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with `disMacro` to create computed display strings
nextTime	Next time stamp when the schedule transition
nextVal	Next value the schedule will transition to
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
siteRef	Reference to site which contains the entity
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data

calendarGrid

Configures the items for a daily calendar. See schedule for further details.

meta


def	calendarGrid
is	grid
lib	lib:schedule
tagOn	calendar

supertypes


val	Data value type
grid	Two dimension table of columns and rows

calendarRef

Used to chain a calendar to a schedule or another calendar.

meta


def	calendarRef
is	ref
lib	lib:schedule
of	calendar

supertypes


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

lib schedule

Overview

The scheduleExt is provides a scheduling engine to:

schedule occupancy hours and building modes
schedule setpoints
schedule holidays and special events

The schedule engine is implemented using two concepts:

calendars: configure each day of the year into an enumerated string mode
schedules: configure each time of day to an output value such an occupancy mode or setpoint value

Calendars may be associated with schedules and other calendars to share a common configuration for classification of days.

Calendar

A calendar classifies each day of the year to a mode string. For example modes might be "Holiday" or a school system might classify dates as "In-Session" and "Out-Session".

The following tags are used to configure a calendar record:

dis: display name
calendar: marker tag for a calendar entity
calendarGrid: grid of calendar items
tz: timezone to use for computing daily transitions (if omitted host's default timezone is used)
calendarRef: used to chain calendars together

In addition calendars can be promoted to full points with the point tag.

The calendarGrid tag is used to configure zero or more calendar items. Items are saved as a grid. The following rules are used to encode items:

The val tag is used to encode each item's string mode value. Values must start with alpha char must not contain the special characters "\n \r ; , + $ \ / | " or quote chars
The dis tag provides comment on the specific item
Dates are encoded as strings as "YYYY-MM-DD" or "*-MM-DD" to wildcard the year

The following tags define how the item's dates are computed:

date: a single date with or without a wildcard year encoded as string where wildcard is encoded as "*"
dateSpan: a range of dates from an inclusive start and end date encoded as "start..end" string. The dates may both wildcard the year or use an explicit year, but cannot span years.
weekdays: a list of weekdays serialized as a comma separated string of sun, mon, tue, wed, thu, fri, sat - for example "mon,tue,wed"
calendar: if a calendarRef is configured, this item maps a series of values from the chain calendar separated by comma
dateRule: a wildcard rule encoded as a string used to handle special cases like "fourth Thursday of November", or "closest weekday to July 4th" (discussed in detail below)

The following illustrates each of the different calendar item types:

dis: "Calendar with Dates"
calendar
calendarGrid:Zinc:
  ver: "3.0"
  val,             date
  "Date",          "2012-07-04"
  "Date-Wildcard", "*-01-01"

dis: "Calendar with DateSpans"
calendar
calendarGrid:Zinc:
  ver: "3.0"
  val,                 dateSpan
  "DateSpan",          "2012-08-01..2012-08-03"
  "DateSpan-Wildcard", "*-08-04..*-08-06"

dis: "Calendar with Weekdays"
calendar
calendarGrid:Zinc:
  ver: "3.0"
  val,        weekdays
  "Weekends", "sun,sat"

dis: "Calendar Chaining"
calendar
calendarGrid:Zinc:
  ver: "3.0"
  val,        calendar
  "Calendar", "Summer-Session,Holiday"

The dateRule option is used to create special rules which don't map cleanly to dates or weekdays. The general format of a rule is:

<rule> := <basic-date-rule> | <closest-weekday-to-rule>
<basic-date-rule>      := <num> <weekday> "in" <month>
<closest-weekday-rule> := "closest-weekday-to" <wildcard-date>
<num>            := "1st" | "2nd" | "3rd" | "4th" | "last"
<weekday>        := "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"
<month>          := "jan" | "feb" | "mar" | "apr" | "may" | "jun" |
                    "jul" | "aug" | "sep" | "oct" | "nov" | "dec"
<wildcard-date>  := <*-MM-DD>

Note that weekday and month are the standardized names in Weekday and Month system APIs.

dis: "Date Rules"
calendar
calendarGrid:Zinc:
  ver: "3.0"
  val,                      dateRule
  "Martin Luther King Day", "3rd mon in jan"
  "George Washington Day",  "3rd mon in feb"
  "Memorial Day",           "last mon in may"
  "Labor Day",              "1st mon in sep"
  "Thanksgiving",           "4th thu in nov"
  "Independence Day"        "closest-weekday-to *-07-04"

The closest-weekday-to rule is useful for situations where holidays need to be observed on the closest weekday if they fall on a weekend. In the example above, the closest-weekday-to rule will match under the given conditions:

If July 4th falls on a weekday for a particular year, then it matches that date.
If July 4th falls on a Saturday for a particular year, then July 3rd will match (Friday - i.e. the closest weekday) .
If July 4th falls on a Sunday for a particular year, then July 5th will match (Monday - i.e. the closest weekday).

Items are declared from highest priority to lowest priority. When computing the value of a given date, the first matching item determines the output value.

The scheduling engine maintains the current value of a calendar using the following tags:

curVal: the current string mode for today or omitted if no mode is active for today
curStatus: status mode as "ok" or "fault" if calendar is not configured correctly
curErr: error message if calendar is in fault

Schedule

Schedules are used to output a configured value for each time of the day. They may be used to configure occupancy, equipment modes, or setpoints.

The following tags are used to configure a schedule record:

dis: display name
schedule: marker tag for a schedule entity
point: all schedules are points
scheduleGrid: grid of schedul items
tz: timezone to use for computing current value (if omitted host's default timezone is used)
calendarRef: used to configured calendar based items

The scheduleGrid tag is used to configure zero or more schedule items. Items are saved as a grid. The following rules are used to encode items:

val: tag is used to encode the items value
dis tag provides comment on the specific item
start: starting time of the item (00:00 is used for midnight at start of day)
end: ending time of the item (00:00 is used for midnight at end of the day)
Dates for the item follow the pattern as Calendar dates using the date, dateSpan, weekdays, or calendar tags

Items are declared from highest priority to lowest priority. When computing the value of a given timestamp, the first matching item which is active for that date and time determines the output value.

The scheduling engine maintains the current value of a schedule using the following tags:

curVal: the current value for right now or missing if auto/null
curStatus: status mode as "ok" or "fault" if schedule is not configured correctly
curErr: error message if schedule is in fault
nextVal: the next value for the schedule
nextTime: timestamp of next transition to a new span

The following illustrates a simple schedule which is on from 9am to 5pm on weekdays and a special event on Aug 11th to turn off early at 3pm.

dis: "Simple Schedule"
schedule
scheduleGrid:Zinc:
  ver: "3.0"
  val, weekdays, date,       start, end
  T,   "12345",  N,          9:00,  17:00
  F,   N,       "2012-08-11" 15:00, 17:00

Schedulable

Writable points with the writable tag may be made schedulable which binds a schedule to a level of the point's priority array. The schedule engine will automatically push any changes to the schedule's curVal to the point's priority array. Schedulable points are configured by defining the priority level with the schedulable tag and the schedule to bind to via the scheduleRef tag.

def

func:scheduleHis

scheduleHis(scheduleRec, dates, opts: {}, yield: null)

Compute a historical or future timeline of a schedule record. This function may be configured using hisFunc to turn in a schedule into a computed history. Or this function may be called with a schedule rec and a date range to returns a history grid of the schedule.

Time spans of the schedule which are auto/null are returned in the results with a null value. But these nulls may be processed incorrectly if performing a join with other histories or using history functions which treat null as an unaligned, sparse va

meta


def	func:scheduleHis
hisFuncReady	✓
is	func
lib	lib:schedule
name	scheduleHis

supertypes


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

def

func:scheduleSync

scheduleSync(timeout: null)

Block until any schedule changes are refreshed.

meta


admin	✓
def	func:scheduleSync
is	func
lib	lib:schedule
name	scheduleSync

supertypes


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

def

func:scheduleValAt

scheduleValAt(scheduleRec, ts)

Return the scheduled value at the given timestamp.

meta


def	func:scheduleValAt
is	func
lib	lib:schedule
name	scheduleValAt

supertypes


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

def

nextTime

Next time stamp when the schedule transition. Also see nextVal.

meta


def	nextTime
is	dateTime
lib	lib:schedule
tagOn	schedule, calendar
transient	✓

supertypes


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

def

nextVal

Next value the schedule will transition to. Also see nextTime.

meta


def	nextVal
is	scalar
lib	lib:schedule
tagOn	schedule, calendar
transient	✓

supertypes


val	Data value type
scalar	Scalar is an atomic value kind

def

schedulable

Binds a schedule to a writable point. The value must be a number between 16 and 1 which indicates the priority level used to write the schedules current value. See schedule.

meta


def	schedulable
is	int
lib	lib:schedule
maxVal	16
minVal	1

supertypes


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

def

schedule

Marker tag for a schedule entity.

meta


def	schedule
is	point
lib	lib:schedule

usage


schedule point

supertypes


marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator


cur	Supports current value
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
his	Supports historization of data
id	Defines the unique identifier of an entity in system using a `ref` value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with `disMacro` to create computed display strings
nextTime	Next time stamp when the schedule transition
nextVal	Next value the schedule will transition to
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
scheduleGrid	Configures the items for a schedule
siteRef	Reference to site which contains the entity
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data

def

scheduleGrid

Configures the items for a schedule. See schedule for further details.

meta


def	scheduleGrid
is	grid
lib	lib:schedule
tagOn	schedule

supertypes


val	Data value type
grid	Two dimension table of columns and rows

def

scheduleRef

Associates a schedulable with its schedule.

meta


def	scheduleRef
is	ref
lib	lib:schedule
of	schedule
tagOn	tariffCharge, writable-point

supertypes


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

def

scheduleVal

The string name/encoding of a schedule value

meta


def	scheduleVal
is	str
lib	lib:schedule
tagOn	tariffCharge

supertypes


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

def

view:schedule

Fresco UI view. See Views

meta


appName	schedule
def	view:schedule
disKey	ui::schedule
icon	view
is	view
lib	lib:schedule

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
view	Fresco UI view

src

view:      { uiType:"scheduleExt::ScheduleBuilder"}
spanCal:   { var kind:"Span" input defVal:Span("thisYear") spanModes:["year"] }
spanSched: { var kind:"Span" input defVal:Span("thisWeek") }
calNew:    { action:"recNew" defName:"calendar" refresh }
calEdit:   { action:"recEdit" defName:"calendar" refresh }
schedNew:  { action:"recNew" defName:"schedule" refresh }
schedEdit: { action:"recEdit" defName:"schedule" refresh }
dup:       { action:"recDup" refresh }
trash:     { action:"recTrash" refresh }
data:      { expr:"readAll(schedule or calendar)" }

lib-schedule 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

apps ​

funcs ​

views ​

app:schedule ​

calendar ​

calendarGrid ​

calendarRef ​

lib schedule ​

Overview ​

Calendar ​

Schedule ​

Schedulable ​

func:scheduleHis ​

scheduleHis(scheduleRec, dates, opts: {}, yield: null) ​

func:scheduleSync ​

scheduleSync(timeout: null) ​

func:scheduleValAt ​

scheduleValAt(scheduleRec, ts) ​

nextTime ​

nextVal ​

schedulable ​

schedule ​

scheduleGrid ​

scheduleRef ​

scheduleVal ​

view:schedule ​

src ​

`lib-schedule` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

apps

funcs

views

app:schedule

calendar

calendarGrid

calendarRef

lib schedule

Overview

Calendar

Schedule

Schedulable

func:scheduleHis

scheduleHis(scheduleRec, dates, opts: {}, yield: null)

func:scheduleSync

scheduleSync(timeout: null)

func:scheduleValAt

scheduleValAt(scheduleRec, ts)

nextTime

nextVal

schedulable

schedule

scheduleGrid

scheduleRef

scheduleVal

view:schedule

src