		@@ -5,3 +5,3 @@ {
		"description": "High speed Synchronous and Asynchronous access to M-like databases from Node.js.",
		"version": "1.0.4",
		"version": "1.1.5a",
		"maintainers": "Chris Munt <cmunt@mgateway.com>",
		@@ -8,0 +8,0 @@ "homepage": "https://github.com/chrisemunt/mg-dbx",

124

README.md

		@@ -6,3 +6,3 @@ # mg-dbx
		Chris Munt <cmunt@mgateway.com>
		7 September 2019, M/Gateway Developments Ltd [http://www.mgateway.com](http://www.mgateway.com)
		4 October 2019, M/Gateway Developments Ltd [http://www.mgateway.com](http://www.mgateway.com)

		@@ -55,3 +55,3 @@ * Verified to work with Node.js v4 to v12.

		var dbx = require('mg-dbx');
		var dbx = require('mg-dbx').dbx;

		@@ -110,3 +110,6 @@ ### Create a Server Object

		#### Additional (optional) properties for the open() method

		* multithreaded: A boolean value to be set to 'true' or 'false' (default multithreaded: false). Set this property to 'true' if the application uses multithreaded techniques in JavaScript (e.g. V8 worker threads).

		### Invocation of database commands
		@@ -231,2 +234,113 @@

		#### Increment the value of a global node

		Synchronous:

		var result = <global>.increment(<key>, <increment_value>);

		Asynchronous:

		<global>.increment(<key>, <increment_value>, callback(<error>, <result>));

		Example (increment the value of the "counter" node by 1.5 and return the new value):

		var result = person.increment("counter", 1.5);


		#### Lock a global node

		Synchronous:

		var result = <global>.lock(<key>, <timeout>);

		Asynchronous:

		<global>.lock(<key>, <timeout>, callback(<error>, <result>));

		Example (lock global node '1' with a timeout of 30 seconds):

		var result = person.lock(1, 30);

		* Note: Specify the timeout value as '-1' for no timeout (i.e. wait until the global node becomes available to lock).


		#### Unlock a (previously locked) global node

		Synchronous:

		var result = <global>.unlock(<key>);

		Asynchronous:

		<global>.unlock(<key>, callback(<error>, <result>));

		Example (unlock global node '1'):

		var result = person.unlock(1);


		### Cursor based data retrieval

		This facility provides high-performance techniques for traversing records held in database globals.

		#### Specifying the query

		The first task is to specify the 'query' for the global traverse.

		query = db.mglobalquery({global: <global_name>, key: [<seed_key>]}[, <options>]);

		The 'options' object can contain the following properties:

		* multilevel: A boolean value (default: multilevel: false). Set to 'true' to return all descendant nodes from the specified 'seed_key'.
		* getdata: A boolean value (default: getdata: false). Set to 'true' to return any data values associated with each global node returned.
		* format: Format for output (default: not specified). If the output consists of multiple data elements, the return value (by default) is a JavaScript object made up of a 'key' array and an associated 'data' value. Set to "url" to return such data as a single URL escaped string including all key values ('key[1->n]') and any associated 'data' value.

		Example (return all keys and names from the 'Person' global):

		query = db.mglobalquery({global: "Person", key: [""]}, {multilevel: false, getdata: true});

		#### Traversing the dataset

		In Key Order:

		result = query.next();

		In Reverse Key Order:

		result = query.previous();

		In all cases these methods will return 'null' when the end of the dataset is reached.

		Example 1 (return all key values from the 'Person' global - returns a simple variable):

		query = db.mglobalquery({global: "Person", key: [""]});
		while ((result = query.next()) !== null) {
		console.log("result: " + result);
		}

		Example 2 (return all key values and names from the 'Person' global - returns an object):

		query = db.mglobalquery({global: "Person", key: [""]}, multilevel: false, getdata: true);
		while ((result = query.next()) !== null) {
		console.log("result: " + JSON.stringify(result, null, '\t'));
		}


		Example 3 (return all key values and names from the 'Person' global - returns a string):

		query = db.mglobalquery({global: "Person", key: [""]}, multilevel: false, getdata: true, format: "url"});
		while ((result = query.next()) !== null) {
		console.log("result: " + result);
		}

		Example 4 (return all key values and names from the 'Person' global, including any descendant nodes):

		query = db.mglobalquery({global: "Person", key: [""]}, {{multilevel: true, getdata: true});
		while ((result = query.next()) !== null) {
		console.log("result: " + result);
		}

		* M programmers will recognise this last example as the M $Query() command.


		### Invocation of database functions
		@@ -295,1 +409,7 @@

		### v1.1.5 (4 October 2019)

		* Introduce global 'increment()' and 'lock(); methods.
		* Introduce cursor based data retrieval.
		* Introduce outline support for multithreading in JavaScript - currently not stable!.

bin/winx64/node10/mg-dbx.node