DB

addChildCategory

Adds a child category for the specified data base node.

Parameters

nodeid   (string (or databasenode))   
Data node identifier path (or databasenode object)

category   (table (or string))   
New category information (or name)

addEventHandler

Add a general event handler callback function.

The handler function should have the following signature: [function name]([parameters]). The parameters will vary depending on the event the function is attached to, as follows.

• [onAuxCharLoad] parameters = (nodeCharAdded)

  • This event is fired when a Character record is loaded from another campaign.

• [onDataLoaded] parameters = ()

  • This event is fired when the database has finished loading locally. This happens immediately on the GM side; but can take a bit to stream in on the Player side.

• [onExport] parameters = (nodeExport, fileName, childNameTagOverride, isListNode)

  • This event is fired when a record is exported to a file.

• [onImport] parameters = (nodeImport)

  • This event is fired when a record is imported from a file.

Parameters

event   (string)   
The event to be captured (see function details)

callback   (function)   
The function to be called when the event triggers

addHandler

Add an event handler callback function to a specified database event on any node matching the specified database path.

The handler function should have the following signature: [function name]([parameters]). The parameters will vary depending on the database event the function is attached to, as follows.

* [onAdd] parameters = (nodeAdded)

* [onCategoryChange] parameters = (nodeChanged)

* [onChildAdded] parameters = (nodeParent, nodeChildAdded)

* [onChildCategoriesChange] parameters = (nodeParent)

* [onChildDeleted] parameters = (nodeParent)

* [onChildUpdate] parameters = (nodeParent, bListchanged)

* [onDelete] parameters = (nodeToBeDeleted)

* [onIntegrityChange] parameters = (nodeChanged)

* [onUpdate] parameters = (nodeUpdated)

Parameters

nodepath   (string)   
A data base path identifier. The '*' character can be used as a wildcard for a path segment.

event   (string)   
The event to be captured (onUpdate, onAdd, onDelete, onObserverUpdate, onChildAdded, onChildUpdate, onChildDeleted, onIntegrityChange)

callback   (function)   
The function to be called when the event triggers

addHolder

This function adds the specified user as a holder for the specified database node and all child nodes. If the owner flag is set, the user will also be able tode modify the contents of data nodes. In such a case, any existing ownership is revoked.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

username   (string)   
The username of the user gaining the status

owner   (boolean)   
If true, the user will also be flagged as the owner of the node.

backup

Creates a backup of the current database, saved to a unique file name. (db.script.#.xml)

convertCampaign

Converts the current campaign to a different specified ruleset.

Parameters

ruleset   (string)   
Target ruleset for conversion

copyNode

This function can be used to copy the contents of a data base node, using data node identifier paths. Either paths or objects can be used as parameters.

Parameters

sourcenodeid   (string (or databasenode))   
The data node identifier path (or a databasenode object) for the source node

destnodeid   (string (or databasenode))   
A data node identifier path (or a databasenode object) for the destination node

Return values

(databasenode)
A databasenode object representing the destination node, or nil if the node was unable to be created for any reason.

createChild

Create, or if it already exists fetch, the specified child node under the specified node.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the source node

name   (string)   [optional]
A relative node identifier specifying the child node to find. If this parameter is omitted, a new unique node name will be generated.

type   (string)   [optional]
The type of node to create. If this parameter is omitted, an intermediate node will be created. Leaf nodes can be of types "number", "string", "formattedtext", "image", "dice" or "windowreference".

Return values

(databasenode)
If the node already exists, the return value is a reference to that node. If it was created, a reference to the created node is returned. If there was an error, returns nil.

createChildAndCopy

Create a child node under parentdestnode using automatic default database ID naming; and copy the data source node data into the new node. [Requires v4.4.7+]

Parameters

parentdestnode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the parest destination node

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the source node

Return values

(databasenode)
A reference to the created node is returned. If there was an error, returns nil.

createNode

This function creates a new top level data base node of the given type.

Parameters

nodeid   (string)   
A data base node identifier

type   (string)   [optional]
The type of node to create. If this parameter is omitted, an intermediate node will be created. Leaf nodes can be of types "number", "string", "formattedtext", "image", "dice" or "windowreference".

Return values

(databasenode)
A databasenode object representing the created node, or nil if the operation failed

deleteChild

Deletes the specified child node under the specified node. (if it exists)

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

name   (string)  [optional]
A relative node identifier specifying the child node to delete

deleteChildren

Deletes all children under the specified node. (if it exists)

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

subpath (string)
A relative node identifier specifying the node to delete children from (if sourcenode is a databasenode object)

deleteNode

This function deletes a data base node.

Parameters

nodeid   (string (or databasenode))   
Data node identifier path (or databasenode object)

export

This function exports an XML data file to the host's hard drive containing the contents of the specified database node.

A root node to contain the exported contents is always created in the XML data file.

The export will follow these criteria depending on the rewrite and listexport parameters:

If rewrite and listexport not defined, then the data file root node will contain an export of all the children of the specified node.

If rewrite is defined but listexport is missing or false, then the data file root node will contain a tag set using the value of the rewrite parameter which will contain an export of all the children of the specified node. (Ex: To export a single character from a ruleset, DB.export("output.xml", "charsheet.id-00001", "character"))

If rewrite is defined and listexport is true, then the exporter will assume that the node to export is a list node. The data file root node will contain a tag set for each child record of the target database using the value of the rewrite parameter instead of the child node ID which will contain an export of all the children of the matching child node. (Ex: To export all characters from a ruleset, DB.export("output.xml", "charsheet", "character", true))

Parameters

filename   (string)   
The name of the file to be imported.

targetnode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

rewrite   (string)   [optional]
See function description.

listexport   (boolean)   [optional]
See function description.

findNode

This function can be used to find a data base node in a global scope based on a global database node identifier.

Parameters

nodeid   (string)   
A global data base node identifier

Return values

(databasenode)
A databasenode object representing the given identifier, or nil if the node was not found

getCategory

Retrieves the category of the specified database node.

Parameters

nodeid   (string (or databasenode))   
Data node identifier path (or databasenode object)

Return values

(string)
Returns the category string of this database node, or empty string if the no category specified.

getChild

Fetches the specified child node under the specified node.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

name   (string)   
A relative node identifier specifying the child node to find

Return values

(databasenode)
A databasenode object representing the node, or nil if the node could not be found or the specified node identifier does not exist.

getChildCategories

Gets the child categories for the specified data base node.

Parameters

nodeid   (string (or databasenode))   
Data node identifier path (or databasenode object)

Return values

(table)
An integer-indexed table of category records. Each category record is a table with the following fields (name, mergeid, base, decal).

getChildCount

Get the number of child nodes belonging to the specified node.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

subpath (string)
A relative node identifier specifying the node to delete children from (if sourcenode is a databasenode object)

Return values

(number)
The number of child nodes, or zero if database node does not exist.

getChildList

Get all the child nodes of the specified node via numerical key.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

subpath (string)
A relative node identifier specifying the node to get children from (if sourcenode is a databasenode object)

Return values

(table)
The child nodes are returned as databasenode objects in a table with numerical keys. If the database node does not exist, an empty table is returned.

getChildren

Get all the child nodes of the specified node/path via name key.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

subpath (string)
A relative node identifier specifying the node to get children from (if sourcenode is a databasenode object)

Return values

(table)
The child nodes are returned as databasenode objects in a table with keys corresponding to the names of the child nodes. If the database node does not exist, an empty table is returned.

getChildrenGlobal

Get all the child nodes of the specified path. The path to use in the child lookup will be calculated from the parameters, then any children of that path will be compiled across the campaign database as well as all loaded module databases.

Parameters

source   (databasenode)   [optional]
Optional source node.

sourcepath   (string)   
Absolute path (if no database node parameter), or relative path from the database node parameter.

Return values

(table)
The child nodes are returned as databasenode objects in a table with keys corresponding to the names of the child nodes. If the database node does not exist, an empty table is returned.

getDefaultChildCategory

Gets the default child category for the specified data base node. When new child nodes are created under this node, the default category is given to those child nodes.

Return values

(string)
The name of the default category assigned to child nodes under the specified node.

getHolders

This function returns a list of all users registered as holders for the specified database node. Holders will be notified of changes to the node value. Users are automatically added to the holder list as a result of window sharing operations.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

Return values

(table)
Returns an integer indexed table containing the usernames of all registered holders for this node.

getImportRulesetVersion

Returns the release number of the ruleset used to save the data currently being imported (or last imported if called after import event).

Return values

(number)
The major version number(number)
The minor version number(table)
A table containing the major version number of each ruleset layer, where the key is the name of the ruleset layer.(table)
A table containing the minor version number of each ruleset layer, where the key is the name of the ruleset layer.

getImportVersion

Returns the version number of the FG client used to save the data currently being imported (or last imported if called after import event).

Return values

(number)
The major version number(number)
The minor version number

getModule

Retrieves the name of the module the data base node was loaded from.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

Return values

(string)
Returns the name of the module the node was loaded from, or empty string if the node was not loaded from a module

getName

Returns a database node name from the databasenode parameter provided. This only returns the immediate node name. If you want the full path, see DB.getPath API.

Parameters

node   (databasenode)
A databasenode object to be queried.

Return values

(string)
The string representation of the databasenode name

getOwner

This function returns the username of the client acting as the current owner of the specified node. Only the GM or the node owner can alter the value of the database node contents.

Parameters

nodeid   (string (or databasenode))   
Data node identifier path (or databasenode object)

Return values

(string)
Returns the username of the user owning the node, or nil if no owner is registered.

getParent

Fetches the parent of the specified node.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

Return values

(databasenode)
A databasenode object representing the parent node, or nil if the current node is a root level node or the specified node identifier does not exist.

getPath

Returns a database path comprised of the optional databasenode parameter and any path parameters provided. The module portion of the path returned will be inherited from the databasenode parameter. (if provided, and if the node is from a module)

Database paths are of the form: [node].(...).[node][@Module Name]

where there can be any number of valid XML tag names concatenated by periods to form the main path and the at symbol and module name is optional.

Parameters

node   (databasenode)   [optional]
A databasenode object to be used as the basis for the path returned.

value   (...)   [optional]
One or more strings to be appended to database path returned.

Return values

(string)
The string representation of the databasenode path

getRoot

Returns the root node for the specified database. If parameter missing or empty string, then the root of the campaign database is returned. Otherwise, the string is assumed to be a module name.

Parameters

dbname   (string)   
Name of the database

Return values

(databasenode)
A databasenode object representing the root node, or nil if the module specified is not loaded or does not exist.

getRulesetVersion

Returns the release number of the ruleset last used to save the data, as defined by the release attribute of the database definition root element.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

Return values

(number)
The major version number(number)
The minor version number(table)
A table containing the major version number of each ruleset layer, where the key is the name of the ruleset layer.(table)
A table containing the minor version number of each ruleset layer, where the key is the name of the ruleset layer.

getText

Returns a textual representation of the value contained in the specified database node. If the node type is not string, number or formattedtext, then the default values will be returned or nil if no default values specified.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

subpath   (string)   [optional]
If the first parameter has type databasenode, then this parameter specifies the relative data node identifier path from the specified node object.

default   (...)   [optional]
The value(s) to be returned if getText fails. (node does not exist; or not string, number or formattedtext value type)

Return values

(string)
Returns the string value of the database node value.

getType

Get the string identifying the type of the specified node. The possible values are "node" (representing an intermediate node), "number", "string", "formattedtext", "image", "dice" and "windowreference".

Parameters

nodeid   (string (or databasenode))   
Data node identifier path (or databasenode object)

Return values

(string)
The type string

getValue

Returns the value contained in the specified source/path parameters. The return value(s) vary depending on the type of the node. If the node does not exist or if the node is a non-value type, then the default values passed in will be returned or nil if no default values are specified.

Parameters

sourcenode   (databasenode)
A databasenode object representing the parent of the target node

relativepath (string)   [optional]
If the first parameter has type databasenode, then this parameter specifies the relative data node identifier path from the specified node object.

absolutepath   (string)   
A data base path identifier.

default   (...)   [optional]
The value(s) to be returned if getValue fails. (node does not exist; or non-value node)

Return values

(...)
Returns data contained in the database node

getVersion

Returns the version number of the FG client last used to save the data, or since the last updateVersion call.

Parameters

sourcenode   (string (or databasenode))   
A data node identifier path (or a databasenode object) representing the target node

Return values

(number)
The major version number(number)
The minor version number

import

This function imports an XML data file from the host's hard drive as children of the specified database node.

The root node of the XML data file is always ignored.

If a list child name is specified, then the target node will be assumed to be a list node, and each XML record under the data file root node with the given list child name will instantiate a unique list record and copy the contents from the XML sub-record to the new unique list record. (Ex: To import all characters from an XML file, DB.import("output.xml", "charsheet", "character"))