Funcs

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

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

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

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

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.

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)

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

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

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

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)

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")

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

Examples:

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

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})

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

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)

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 stripped unless the {mod} option is specified. The id tag is not stripped for cases when adding records with swizzled ids; pass {-id} in options to strip the id tag also.

Examples:

// strip uncommittable tags and keep id
toCommit: rec.stripUncommittable

// strip uncommittable tags and the id tag
toCommit: rec.stripUncommittable({-id})

// strip uncommittable tags, but keep id and mod
toCommit: rec.stripUncommittable({mod})

Coerce a value to a Ref identifier:

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

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

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

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

Return system meta as dict

Return current project meta as dict

Return grid of runtime xeto libs and current status:

• name: library dotted name string
• libBasis: basis enumeration string
• libStatus: status enumeration string
• other cols subject to change

Reload all the xeto libraries in project

Enable one or more Xeto libs by name:

libAdd("ph.points")
libAdd(["ph.points", "ph.equips"])

Disable or more Xeto libs by name:

libRemove("ph.points")
libRemove(["ph.points", "ph.equips"])

Return grid of exts:

• name: library dotted name string
• libBasis: basis enumeration string
• extStatus: status enumeration string
• other cols subject to change

Return ext settings dict for given dotted lib name:

extSettings("hx.task")

Update ext settings for given dotted lib name:

extSettingsUpdate("hx.task", {maxThreads:20})

Read a companion spec or instance by name - see ProjCompanion.readByName. Examples:

companionReadByName("MySpec")
companionReadByName("my-instance")

Add new spec or instance to companion lib - see ProjCompanion.add. Examples:

companionAdd({rt:"spec", name:"MySpec", base:@sys::Dict, spec:@sys::Spec})
companionParse("MySpec: Dict { dis: Str }").companionAdd

Update existing spec or instance in companion lib - see ProjCompanion.update. Examples:

companionReadByName("MySpec").merge({base:@sys::Scalar}).companionUpdate
companionReadByName("myFunc").merge({axon:"(x)=>x"}).companionUpdate

Remove a spec or instance from companion lib - see ProjCompanion.remove. The id argument can be any value accepted by toRecId(). Examples:

companionRemove(@123)
companionReadByName("MySpec").companionRemove

Parse xeto source to its companion lib AST representation - see ProjCompanion.parse. Pipe to companionAdd() or companionUpdate() to update from Xeto source. Examples:

companionParse("MySpec: Dict { dis: Str }")
companionParse("@my-instance: Dict {}")

Print companion AST rec representation back a Xeto string - see ProjCompanion.print. Examples:

companionRead("MySpec").companionPrint

Create func companion lib AST representation - see ProjCompanion.parseAxon. Pipe to companionAdd() or companionUpdate() to update from Xeto source. Examples:

companionParseAxon("myFunc", "(a)=>a*2")
companionParseAxon("myFunc", "(a)=>a*2", {admin})

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

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 RuntimeWatches.open and Watches.

Example:

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

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 Watch.poll and Watches.

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

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

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

Return Runtime.isSteadyState

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

Return list of installed Fantom pods

Return the installed timezone database as Grid with following columns:

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

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