@Axon
static Dict about()

Return about dict

@Axon { admin=true }
static Obj? commit(Obj diffs)

Commit one or more diffs to the folio database. The argument may be one of the following:

• result of diff()
• list of diff() to commit multiple diffs at once
• stream of diff(); see Streams.

If one diff is passed, return the new record. If a list of diffs is passed return a list of new records.

This is a synchronous blocking call which will return the new record or records as the result.

Examples:

// add new record
newRec: commit(diff(null, {dis:"New Rec!"}, {add}))

// add someTag to some group of records
readAll(filter).toRecList.map(r => diff(r, {someTag})).commit

@Axon
static Dict context()

Get the current context as a Dict with the following tags:

• username for current user
• userRef id for current user
• locale current locale SkySpark tags:
• projName if evaluating in context of a project
• nodeId local cluster node id
• ruleRef if evaluating in context of a rule engine
• ruleTuning if evaluating in context of rule engine

@Axon
static Diff diff(Dict? orig, Dict? changes, Dict? flags := null)

Construct a modification "diff" used by commit. The orig should be the instance which was read from the database, or it may be null only if the add flag is passed. Any tags to add/set/remove should be included in the changes dict.

The following flags are supported:

• add: indicates diff is adding new record
• remove: indicates diff is removing record (in general you should add trash tag instead of removing)
• transient: indicate that this diff should not be flushed to persistent storage (it may or may not be persisted).
• force: indicating that changes should be applied regardless of other concurrent changes which may be been applied after the orig version was read (use with caution!)

Examples:

// create new record
diff(null, {dis:"New Rec", someMarker}, {add})

// create new record with explicit id like Diff.makeAdd
diff(null, {id:151bd3c5-6ce3cb21, dis:"New Rec"}, {add})

// set/add dis tag and remove oldTag
diff(orig, {dis:"New Dis", -oldTag})

// set/add val tag transiently
diff(orig, {val:123}, {transient})

@Axon
static Bool isSteadyState()

Return HxRuntime.isSteadyState

@Axon
static Bool isWatched(Obj rec)

Return if given record is under at least one watch. The rec argument can be any value accepted by toRecId().

@Axon { admin=true }
static Dict libAdd(Str name, Dict? tags := null)

Enable a library by name in the runtime:

libAdd("mqtt")

@Axon { admin=true }
static Obj? libRemove(Obj name)

Disable a library by name in the runtime:

libRemove("mqtt")

@Axon { admin=true }
static Grid libStatus()

Return grid of enabled libs and their current status. Columns:

• name: library name string
• libStatus: status enumeration string
• statusMsg: additional message string or null

@Axon { admin=true }
static Void passwordSet(Obj key, Str? val)

Store a password key/val pair into current project's password store. The key is typically a Ref of the associated record. If the val is null, then the password will be removed. See Folio.

passwordSet(@abc-123, "password")
passwordSet(@abc-123, null)

@Axon { admin=true }
static Grid pods()

Return list of installed Fantom pods

@Axon
static Dict? read(Expr filterExpr, Expr checked := Literal.trueVal)

Read from database the first record which matches filter. If no matches found throw UnknownRecErr or null based on checked flag. If there are multiple matches it is indeterminate which one is returned. See readAll for how filter works.

Examples:

read(site)                 // read any site rec
read(site and dis=="HQ")   // read site rec with specific dis tag
read(chiller)              // raise exception if no recs with chiller tag
read(chiller, false)       // return null if no recs with chiller tag

@Axon
static Grid readAll(Expr filterExpr, Expr? optsExpr := null)

Reall all records from the database which match the filter. The filter must an expression which matches the filter structure. String values may parsed into a filter using parseFilter() function.

Options:

• limit: max number of recs to return
• sort: sort by display name

Examples:

readAll(site)                      // read all site recs
readAll(equip and siteRef==@xyz)   // read all equip in a given site
readAll(equip, {limit:10})         // read up to ten equips
readAll(equip, {sort})             // read all equip sorted by dis

@Axon
static Obj readAllStream(Expr filterExpr)

Reall all records which match filter as stream of Dict records. See Streams.

@Axon
static Grid readAllTagNames(Expr filterExpr)

Return the intersection of all tag names used by all the records matching the given filter. The results are returned as a grid with following columns:

• name: string name of the tag
• kind: all the different value kinds separated by "|"
• count: total number of recs with the tag Also see readAllTagVals and gridColKinds().

Examples:

// read statistics on all tags used by equip recs
readAllTagNames(equip)

@Axon
static Grid readAllTagVals(Expr filterExpr, Expr tagName)

Return the range of all the values mapped to a given tag name used by all the records matching the given filter. This method is capped to 200 results. The results are returned as a grid with a single val column. Also see readAllTagNames.

Examples:

// read grid of all unique point unit tags
readAllTagVals(point, "unit")

@Axon
static Dict? readById(Ref? id, Bool checked := true)

Read a record from database by id. If not found throw UnknownRecErr or return null based on checked flag. In Haxall all refs are relative, but in SkySpark refs may be prefixed with something like "p:projName:r:". This function will accept both relative and absolute refs.

Examples:

readById(@2b00f9dc-82690ed6)          // relative ref literal
readById(@:demo:r:2b00f9dc-82690ed6)  // project absolute literal
readById(id)                          // read using variable
readById(equip->siteRef)              // read from ref tag

@Axon
static Dict? readByIdPersistentTags(Ref id, Bool checked := true)

Given record id, read only the persistent tags from Folio. Also see readByIdTransientTags and readById.

@Axon
static Dict? readByIdTransientTags(Ref id, Bool checked := true)

Given record id, read only the transient tags from Folio. Also see readByIdPersistentTags and readById.

@Axon
static Grid readByIds(Ref[] ids, Bool checked := true)

Read a list of record ids into a grid. The rows in the result correspond by index to the ids list. If checked is true, then every id must be found in the database or UnknownRecErr is thrown. If checked is false, then an unknown record is returned as a row with every column set to null (including the id tag). Either relative or project absolute refs may be used.

Examples:

// read two relative refs
readByIds([@2af6f9ce-6ddc5075, @2af6f9ce-2d56b43a])

// read two project absolute refs
readByIds([@p:demo:r:2af6f9ce-6ddc5075, @p:demo:r:2af6f9ce-2d56b43a])

// return null for a given id if it does not exist
readByIds([@2af6f9ce-6ddc5075, @2af6f9ce-2d56b43a], false)

@Axon
static Obj readByIdsStream(Ref[] ids, Bool checked := true)

Read a list of ids as a stream of Dict records. If checked if false, then records not found are skipped. See Streams.

@Axon
static Number readCount(Expr filterExpr)

Return the number of records which match the given filter expression.

Examples:

readCount(point)    // return number of recs with point tag

@Axon
static Dict? readLink(Ref? id)

Read a record Dict by its id for hyperlinking in a UI. Unlike other reads which return a Dict, this read returns the columns ordered in the same order as reads which return a Grid.

@Axon { admin=true }
static Grid services()

Grid of installed services. Format of the grid is subject to change.

@Axon
static Obj stripUncommittable(Obj val, Obj? opts := null)

Strip any tags which cannot be persistently committed to Folio. This includes special tags such as hisSize and any transient tags the record has defined. If val is Dict, then a single Dict is returned. Otherwise val must be Dict[] or Grid and Dict[] is returned. The mod tag is always stripped. The id tag is not stripped for cases when adding records with swizzled ids; pass {-id} for options to strip the id tag also.

@Axon
static Dict toRec(Obj? val)

Coerce a value to a record Dict:

• Row or Dict returns itself
• Grid returns first row
• List returns first row (can be either Ref or Dict)
• Ref will make a call to read database

@Axon
static Ref toRecId(Obj? val)

Coerce a value to a Ref identifier:

• Ref returns itself
• Row or Dict, return id tag
• Grid return first row id

@Axon
static Ref[] toRecIdList(Obj? val)

Coerce a value to a list of Ref identifiers:

• Ref returns itself as list of one
• Ref[] returns itself
• Dict return id tag
• Dict[] return id tags
• Grid return id column

@Axon
static Dict[] toRecList(Obj? val)

Coerce a value to a list of record Dicts:

• null return empty list
• Ref or Ref[] (will make a call to read database)
• Row or Row[] returns itself
• Dict or Dict[] returns itself
• Grid is mapped to list of rows

@Axon
static Grid tzdb()

Return the installed timezone database as Grid with following columns:

• name: name of the timezone
• fullName: qualified name used by Olson database

@Axon
static Grid unitdb()

Return the installed unit database as Grid with following columns:

• quantity: dimension of the unit
• name: full name of the unit
• symbol: the abbreviated Unicode name of the unit

@Axon
static Grid watchAdd(Str watchId, Grid grid)

Add a grid of recs to an existing watch and return the grid passed in.

@Axon
static Obj? watchClose(Str watchId)

Close an open watch by id. If the watch does not exist or has expired then this is a no op. Also see HxWatch.close and Watches.

@Axon
static Grid watchOpen(Grid grid, Str dis)

Open a new watch on a grid of records. The dis parameter is used for the watch's debug display string. Update and return the grid with a meta watchId tag. Also see HxWatchService.open and Watches.

Example:

readAll(myPoints).watchOpen("MyApp|Points")

@Axon
static Grid watchPoll(Obj watchId)

Poll an open watch and return all the records which have changed since the last poll. Raise exception if watchId doesn't exist or has expired. Also see HxWatch.poll and Watches.

@Axon
static Grid watchRemove(Str watchId, Grid grid)

Remove a grid of recs from an existing watch and return grid passed in.