This is a global built in package that provides global level interfaces to the program data base.
See databasenode for more information on data base nodes and their operation.
Interface
addHolder
function addHolder(
sourcenode, username, owner
)
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 to modify the contents of data nodes. In such a case, any existing ownership is revoked.
Warning
This function will only work if running as a host.
Parameters
sourcenode (string (or databasenode))
A data node identifier path (or a
databasenode object) representing the target node
(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.
copyNode
function copyNode(
sourcenodeid, destnodeid
)
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.
Warning
The source database node must exist, and the destination node if it exists already must be the same value type.
Parameters
sourcenodeid (string (or databasenode))
The data node identifier path (or a
databasenode object) for the source node
(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.
createNode
function createNode(
nodeid, [type]
)
This function creates a new top level data base node of the given type.
Warning
Users are adviced against storing preference style data in the database. Using registries is the preferred method for
storing such data.
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
export
function export(
filename, targetnode, [rewrite], [listexport]
)
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))
Warning
This function will only work if running as a host.
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
(string) [optional]
See function description.
listexport (boolean) [optional]
See function description.
findNode
function findNode(
nodeid
)
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
getHolders
function getHolders(
sourcenode
)
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.
Warning
This function will only work if running as a host.
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.
getText
function getText(
sourcenode, [subpath], [default]
)
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
(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.
getValue
function getValue(
sourcenode, [subpath], [default]
)
Returns the value contained in the specified database node. 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 (string (or databasenode))
A data node identifier path (or a
databasenode object) representing the target node
(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 getValue fails. (node does not exist; or non-value node)
Return values
(...)
Returns data contained in the database node
import
function import(
filename, targetnode, [listchildname]
)
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"))
Warning
This function will only work if running as a host.
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
(string) [optional]
See function description.
isReadOnly
function isReadOnly(
sourcenode
)
Determines whether the specified database node can be edited. Reasons for database nodes to be non-editable include:
nodes marked as static, nodes from client or common modules, nodes not owned by client (host owns all nodes)
Parameters
sourcenode (string (or databasenode))
A data node identifier path (or a
databasenode object) representing the target node
Return values
(boolean)
Returns true if the node is not editable, false otherwise
removeAllHolders
function removeAllHolders(
sourcenode
)
This function removes all users from the holder list for the specified database node and all child nodes. The data is deleted from any
client instance and any windows having a deleted node as their data source will be closed.
Warning
This function will only work if running as a host.
Parameters
sourcenode (string (or databasenode))
A data node identifier path (or a
databasenode object) representing the target node
removeHolder
function removeHolder(
sourcenode, username
)
This function removes the specified user from the holder list for the specified database node and all child nodes. The data is deleted from the
client instance and any windows having a deleted node as their data source will be closed.
Warning
This function will only work if running as a host.
Parameters
sourcenode (string (or databasenode))
A data node identifier path (or a
databasenode object) representing the target node
(string)
The username of the user losing the holder status
setValue
function setValue(
sourcenode, [subpath], type, value
)
Sets the data in the specified database node path. If the node exists already, the type value must match the existing database node type. If the node does not exist, a new node will be created with the specified type. The format of the value parameter(s) depends on the type of the node.
Parameters
sourcenode (string (or databasenode))
A data node identifier path (or a
databasenode object) representing the target node
(string) [optional]
If the first parameter has type databasenode, then this parameter specifies the relative data node identifier path from the specified node object.
type (string)
Identifier for the data type of the new or existing node.
value (...)
Data to be placed in the database node
