mg-dbx


Follow
0
Star
0
Details
Releases
Issues
This application is not supported by InterSystems Corporation. Use it at your own risk.

What's new in this version

Modify the project title.

mg-dbx

High speed Synchronous and Asynchronous access to InterSystems Cache/IRIS and YottaDB from Node.js.

Chris Munt cmunt@mgateway.com
15 August 2020, M/Gateway Developments Ltd http://www.mgateway.com

  • Verified to work with Node.js v8 to v14.
  • Two connectivity models to the InterSystems or YottaDB database are provided: High performance via the local database API or network based.
  • Release Notes can be found at the end of this document.

Contents

Pre-requisites

mg-dbx is a Node.js addon written in C++. It is distributed as C++ source code and the NPM installation procedure will expect a C++ compiler to be present on the target system.

Linux systems can use the freely available GNU C++ compiler (g++) which can be installed as follows.

Ubuntu:

   apt-get install g++

Red Hat and CentOS:

   yum install gcc-c++

Apple OS X can use the freely available Xcode development environment.

There are two options for Windows, both of which are free:

If the Windows machine is not set up for systems development, building native Addon modules for this platform from C++ source can be quite arduous. There is some helpful advice available at:

Alternatively there are built Windows x64 binaries available from:

Installing mg-dbx

Assuming that Node.js is already installed and a C++ compiler is available to the installation process:

   npm install mg-dbx

This command will create the mg-dbx addon (mg-dbx.node).

Installing the M support routines

The M support routines are required for:

  • Network based access to databases.
  • Direct access to SQL (either via the API or via the network).
  • The Merge command under YottaDB (either via the API or via the network).

Two M routines need to be installed (%zmgsi and %zmgsis). These can be found in the GitHub source code repository (https://github.com/chrisemunt/mg-dbx)

Installation for InterSystems Cache/IRIS

For InterSystems IRIS and Cache, log in to the Manager UCI and install the zmgsi routines held in either /m/zmgsi_cache.xml or /m/zmgsi_iris.xml as appropriate.

   do $system.OBJ.Load("/m/zmgsi_cache.xml","ck")

Alternatively, for other M systems, log in to the Manager UCI and, using the %RI utility (or similar) load the zmgsi routines held in /m/zmgsi.ro.

Change to your development UCI and check the installation:

   do ^%zmgsi

   M/Gateway Developments Ltd - Service Integration Gateway
   Version: 3.3; Revision 9 (17 June 2020)

Installation for YottaDB

The instructions given here assume a standard 'out of the box' installation of YottaDB deployed in the following location:

   /usr/local/lib/yottadb/r122

The primary default location for routines:

   /root/.yottadb/r1.22_x86_64/r

Copy all the routines (i.e. all files with an 'm' extension) held in the GitHub /yottadb directory to:

   /root/.yottadb/r1.22_x86_64/r

Change directory to the following location and start a YottaDB command shell:

   cd /usr/local/lib/yottadb/r122
   ./ydb

Link all the zmgsi routines and check the installation:

   do ylink^%zmgsi

   do ^%zmgsi

   M/Gateway Developments Ltd - Service Integration Gateway
   Version: 3.3; Revision 9 (17 June 2020)

Note that the version of zmgsi is successfully displayed.

Finally, add the following lines to the interface file (zmgsi.ci in the example used in the db.open() method).

   sqlemg: ydb_string_t * sqlemg^%zmgsis(I:ydb_string_t*, I:ydb_string_t *, I:ydb_string_t *)
   sqlrow: ydb_string_t * sqlrow^%zmgsis(I:ydb_string_t*, I:ydb_string_t *, I:ydb_string_t *)
   sqldel: ydb_string_t * sqldel^%zmgsis(I:ydb_string_t*, I:ydb_string_t *)
   ifc_zmgsis: ydb_string_t * ifc^%zmgsis(I:ydb_string_t*, I:ydb_string_t *, I:ydb_string_t*)

Setting up the network service (for network based connectivity only)

The default TCP server port for zmgsi is 7041. If you wish to use an alternative port then modify the following instructions accordingly.

InterSystems Cache/IRIS

Start the Cache/IRIS-hosted concurrent TCP service in the Manager UCI (the %SYS Namespace):

   do start^%zmgsi(0) 

To use a server TCP port other than 7041, specify it in the start-up command (as opposed to using zero to indicate the default port of 7041).

YottaDB

Network connectivity to YottaDB is managed via the xinetd service. First create the following launch script (called zmgsi_ydb here):

   /usr/local/lib/yottadb/r122/zmgsi_ydb

Content:

   #!/bin/bash
   cd /usr/local/lib/yottadb/r122
   export ydb_dir=/root/.yottadb
   export ydb_dist=/usr/local/lib/yottadb/r122
   export ydb_routines="/root/.yottadb/r1.22_x86_64/o*(/root/.yottadb/r1.22_x86_64/r /root/.yottadb/r) /usr/local/lib/yottadb/r122/libyottadbutil.so"
   export ydb_gbldir="/root/.yottadb/r1.22_x86_64/g/yottadb.gld"
   $ydb_dist/ydb -r xinetd^%zmgsis

Create the xinetd script (called zmgsi_xinetd here):

   /etc/xinetd.d/zmgsi_xinetd

Content:

   service zmgsi_xinetd
   {
        disable         = no
        type            = UNLISTED
        port            = 7041
        socket_type     = stream
        wait            = no
        user            = root
        server          = /usr/local/lib/yottadb/r122/zmgsi_ydb
   }
  • Note: sample copies of zmgsi_xinetd and zmgsi_ydb are included in the /unix directory.

Edit the services file:

   /etc/services

Add the following line to this file:

   zmgsi_xinetd          7041/tcp                        # zmgsi

Finally restart the xinetd service:

   /etc/init.d/xinetd restart

Connecting to the database

Most mg-dbx methods are capable of operating either synchronously or asynchronously. For an operation to complete asynchronously, simply supply a suitable callback as the last argument in the call.

The first step is to add mg-dbx to your Node.js script

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

And optionally (as required):

   var mglobal = require('mg-dbx').mglobal;
   var mcursor = require('mg-dbx').mcursor;
   var mclass = require('mg-dbx').mclass;

Create a Server Object

   var db = new dbx();

Open a connection to the database

In the following examples, modify all paths (and any user names and passwords) to match those of your own installation.

InterSystems Cache

API based connectivity

Assuming Cache is installed under /opt/cache20181/

       var open = db.open({
           type: "Cache",
           path:"/opt/cache20181/mgr",
           username: "_SYSTEM",
           password: "SYS",
           namespace: "USER"
         });
Network based connectivity

Assuming Cache is accessed via localhost listening on TCP port 7041

       var open = db.open({
           type: "Cache",
           host: "localhost",
           tcp_port: 7041,
           username: "_SYSTEM",
           password: "SYS",
           namespace: "USER"
         });

InterSystems IRIS

API based connectivity

Assuming IRIS is installed under /opt/IRIS20181/

       var open = db.open({
           type: "IRIS",
           path:"/opt/IRIS20181/mgr",
           username: "_SYSTEM",
           password: "SYS",
           namespace: "USER"
         });
Network based connectivity

Assuming IRIS is accessed via localhost listening on TCP port 7041

       var open = db.open({
           type: "IRIS",
           host: "localhost",
           tcp_port: 7041,
           username: "_SYSTEM",
           password: "SYS",
           namespace: "USER"
         });

YottaDB

API based connectivity

Assuming an 'out of the box' YottaDB installation under /usr/local/lib/yottadb/r122.

       var envvars = "";
       envvars = envvars + "ydb_dir=/root/.yottadb\n"
       envvars = envvars + "ydb_rel=r1.22_x86_64\n"
       envvars = envvars + "ydb_gbldir=/root/.yottadb/r1.22_x86_64/g/yottadb.gld\n"
       envvars = envvars + "ydb_routines=/root/.yottadb/r1.22_x86_64/o*(/root/.yottadb/r1.22_x86_64/r /root/.yottadb/r) /usr/local/lib/yottadb/r122/libyottadbutil.so\n"
       envvars = envvars + "ydb_ci=/usr/local/lib/yottadb/r122/zmgsi.ci\n"
       envvars = envvars + "\n"

       var open = db.open({
           type: "YottaDB",
           path: "/usr/local/lib/yottadb/r122",
           env_vars: envvars
         });
Network based connectivity

Assuming YottaDB is accessed via localhost listening on TCP port 7041

       var open = db.open({
           type: "YottaDB",
           host: "localhost",
           tcp_port: 7041,
         });

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

Return the version of mg-dbx

   var result = db.version();

Example:

   console.log("\nmg-dbx Version: " + db.version());

Returning (and optionally changing) the current directory (or Namespace)

   current_namespace = db.namespace([<new_namespace>]);

Example 1 (Get the current Namespace):

   var nspace = db.namespace();
  • Note this will return the current Namespace for InterSystems databases and the value of the current global directory for YottaDB (i.e. $ZG).

Example 2 (Change the current Namespace):

   var new_nspace = db.namespace("SAMPLES");
  • If the operation is successful this method will echo back the new Namespace name. If not successful, the method will return the name of the current (unchanged) Namespace.

Returning (and optionally changing) the current character set

UTF-8 is the default character encoding for mg-dbx. The other option is the 8-bit ASCII character set (characters of the range ASCII 0 to ASCII 255). The ASCII character set is a better option when exchanging single-byte binary data with the database.

   current_charset = db.charset([<new_charset>]);

Example 1 (Get the current character set):

   var charset = db.charset();

Example 2 (Change the current character set):

   var new_charset = db.charset('ascii');
  • If the operation is successful this method will echo back the new character set name. If not successful, the method will return the name of the current (unchanged) character set.
  • Currently supported character sets and encoding schemes: 'ascii' and 'utf-8'.

Close database connection

   db.close();

Invocation of database commands

Register a global name (and fixed key)

   global = new mglobal(db, <global_name>[, <fixed_key>]);

Or:

   global = db.mglobal(<global_name>[, <fixed_key>]);

Example (using a global named "Person"):

   var person = db.mglobal("Person");

Set a record

Synchronous:

   var result = <global>.set(<key>, <data>);

Asynchronous:

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

Example:

   person.set(1, "John Smith");

Get a record

Synchronous:

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

Asynchronous:

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

Example:

   var name = person.get(1);
  • Note: use get_bx to receive the result as a Node.js Buffer.

Delete a record

Synchronous:

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

Asynchronous:

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

Example:

   var name = person.delete(1);

Check whether a record is defined

Synchronous:

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

Asynchronous:

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

Example:

   var name = person.defined(1);

Parse a set of records (in order)

Synchronous:

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

Asynchronous:

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

Example:

   var key = "";
   while ((key = person.next(key)) != "") {
      console.log("\nPerson: " + key + ' : ' + person.get(key));
   }

Parse a set of records (in reverse order)

Synchronous:

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

Asynchronous:

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

Example:

   var key = "";
   while ((key = person.previous(key)) != "") {
      console.log("\nPerson: " + key + ' : ' + person.get(key));
   }

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

Merge (or copy) part of one global to another

  • Note: In order to use the 'Merge' facility with YottaDB the M support routines should be installed (%zmgsi and %zmgsis).

Synchronous (merge from global2 to global1):

   var result = <global1>.merge([<key1>,] <global2> [, <key2>]);

Asynchronous (merge from global2 to global1):

   <global1>.defined([<key1>,] <global2> [, <key2>], callback(<error>, <result>));

Example 1 (merge ^MyGlobal2 to ^MyGlobal1):

   global1 = new mglobal(db, 'MyGlobal1');
   global2 = new mglobal(db, 'MyGlobal2');
   global1.merge(global2);

Example 2 (merge ^MyGlobal2(0) to ^MyGlobal1(1)):

   global1 = new mglobal(db, 'MyGlobal1', 1);
   global2 = new mglobal(db, 'MyGlobal2', 0);
   global1.merge(global2);

Alternatively:

   global1 = new mglobal(db, 'MyGlobal1');
   global2 = new mglobal(db, 'MyGlobal2');
   global1.merge(1, global2, 0);

Reset a global name (and fixed key)

   <global>.reset(<global_name>[, <fixed_key>]);

Example:

   // Process orders for customer #1
   customer_orders = db.mglobal("Customer", 1, "orders")
   do_work ...

   // Process orders for customer #2
   customer_orders.reset("Customer", 2, "orders");
   do_work ...

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 = new mcursor(db, {global: <global_name>, key: [<seed_key>]}[, <options>]);

Or:

   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: " + JSON.stringify(result, null, '\t'));
   }
  • M programmers will recognise this last example as the M $Query() command.

Traversing the global directory (return a list of global names)

   query = db.mglobalquery({global: <seed_global_name>}, {globaldirectory: true});

Example (return all global names held in the current directory)

   query = db.mglobalquery({global: ""}, {globaldirectory: true});
   while ((result = query.next()) !== null) {
      console.log("result: " + result);
   }

Invocation of database functions

Synchronous:

   result = db.function(<function>, <parameters>);

Asynchronous:

   db.function(<function>, <parameters>, callback(<error>, <result>));

Example:

M routine called 'math':

   add(a, b) ; Add two numbers together
             quit (a+b)

JavaScript invocation:

  result = db.function("add^math", 2, 3);
  • Note: use function_bx to receive the result as a Node.js Buffer.

Direct access to InterSystems classes (IRIS and Cache)

Invocation of a ClassMethod

Synchronous:

   result = new mclass(db, <class_name>, <classmethod_name>, <parameters>);

Or:

   result = db.classmethod(<class_name>, <classmethod_name>, <parameters>);

Asynchronous:

   db.classmethod(<class_name>, <classmethod_name>, <parameters>, callback(<error>, <result>));

Example (Encode a date to internal storage format):

   result = db.classmethod("%Library.Date", "DisplayToLogical", "10/10/2019");
  • Note: use classmethod_bx to receive the result as a Node.js Buffer.

Creating and manipulating instances of objects

The following simple class will be used to illustrate this facility.

   Class User.Person Extends %Persistent
   {
      Property Number As %Integer;
      Property Name As %String;
      Property DateOfBirth As %Date;
      Method Age(AtDate As %Integer) As %Integer
      {
         Quit (AtDate - ..DateOfBirth) \ 365.25
      }
   }

Create an entry for a new Person

   person = db.classmethod("User.Person", "%New");

Add Data:

   result = person.setproperty("Number", 1);
   result = person.setproperty("Name", "John Smith");
   result = person.setproperty("DateOfBirth", "12/8/1995");

Save the object record:

   result = person.method("%Save");

Retrieve an entry for an existing Person

Retrieve data for object %Id of 1.

   person = db.classmethod("User.Person", "%OpenId", 1);

Return properties:

   var number = person.getproperty("Number");
   var name = person.getproperty("Name");
   var dob = person.getproperty("DateOfBirth");

Calculate person's age at a particular date:

   today = db.classmethod("%Library.Date", "DisplayToLogical", "10/10/2019");
   var age = person.method("Age", today);
  • Note: use classmethod_bx, method_bx and getproperty_bx to receive data as a Node.js Buffer.

Reusing an object container

Once created, it is possible to reuse containers holding previously instantiated objects using the reset() method. Using this technique helps to reduce memory usage in the Node.js environment.

Example 1 Reset a container to hold a new instance:

   person.reset("User.Person", "%New");

Example 2 Reset a container to hold an existing instance (object %Id of 2):

   person.reset("User.Person", "%OpenId", 2);

Direct access to SQL: MGSQL and InterSystems SQL (IRIS and Cache)

mg-dbx provides direct access to the Open Source MGSQL engine (https://github.com/chrisemunt/mgsql) and InterSystems SQL (IRIS and Cache).

  • Note: In order to use this facility the M support routines should be installed (%zmgsi and %zmgsis).

Specifying the SQL query

The first task is to specify the SQL query.

   query = new mcursor(db, {sql: <sql_statement>[, type: <sql_engine>]);

Or:

   query = db.sql({sql: <sql_statement>[, type: <sql_engine>]);

Example 1 (using MGSQL):

   query = db.sql({sql: "select * from person"});

Example 2 (using InterSystems SQL):

   query = db.sql({sql: "select * from SQLUser.person", type: "Cache"});

Execute an SQL query

Synchronous:

   var result = <query>.execute();

Asynchronous:

   <query>.execute(callback(<error>, <result>));

The result of query execution is an object containing the return code and state and any associated error message. The familiar ODBC return and status codes are used.

Example 1 (successful execution):

   {
       "sqlcode": 0,
       "sqlstate": "00000",
       "columns": [
                     {
                        "name": "Number",
                        "type": "INTEGER"
                     },
                       "name": "Name",
                        "type": "VARCHAR"
                     },
                       "name": "DateOfBirth",
                        "type": "DATE"
                     }
                  ]
   }

Example 2 (unsuccessful execution):

   {
       "sqlcode": -1,
       "sqlstate": "HY000",
       "error": "no such table 'person'"
   }

Traversing the returned dataset (SQL 'select' queries)

In result-set order:

   result = query.next();

In reverse result-set order:

   result = query.previous();

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

Example:

   while ((row = query.next()) !== null) {
      console.log("row: " + JSON.stringify(result, null, '\t'));
   }

The output for each iteration is a row of the generated SQL result-set. For example:

   {
       "number": 1,
       "name": "John Smith",
   }

SQL cleanup

For 'select' queries that generate a result-set it is good practice to invoke the 'cleanup' method at the end to delete the result-set held in the database.

Synchronous:

   var result = <query>.cleanup();

Asynchronous:

   <query>.cleanup(callback(<error>, <result>));

Reset an SQL container with a new SQL Query

Synchronous:

   <query>.reset({sql: <sql_statement>[, type: <sql_engine>]);

Asynchronous:

   <query>.reset({sql: <sql_statement>[, type: <sql_engine>], callback(<error>, <result>));

Working with binary data

In mg-dbx the default character encoding scheme is UTF-8. When transmitting binary data between the database and Node.js there are two options.

  • Switch to using the 8-bit ASCII character set.
  • Receive the incoming data into Node.js Buffers.

On the input (to the database) side all mg-dbx function arguments can be presented as Node.js Buffers and mg-dbx will automatically detect that an argument is a Buffer and process it accordingly.

On the output side the following functions can be used to return the output as a Node.js Buffer.

  • dbx::function_bx

  • dbx::classmethod_bx

  • mglobal::get_bx

  • mclass::classmethod_bx

  • mclass::method_bx

  • mclass::getproperty_bx

These functions work the same way as their non '_bx' suffixed counterparts. The only difference is that they will return data as a Node.js Buffer as opposed to a type of String.

The following two examples illustrate the two schemes for receiving binary data from the database.

Example 1: Receive binary data from a DB function as a Node.js 8-bit character stream

   <db>.charset('ascii');
   var stream_str8 = <db>.function(<function>, <parameters>);
   <db>.charset('utf-8'); // reset character encoding

Example 2: Receive binary data from a DB function as a Node.js Buffer

   var stream_buffer = <db>.function_bx(<function>, <parameters>);

Using Node.js/V8 worker threads

mg-dbx functionality can now be used with Node.js/V8 worker threads. This enhancement is available with Node.js v12 (and later).

  • Note: be sure to include the property multithreaded: true in the open method when opening database connections to be used in multi-threaded applications.

Use the following constructs for instantiating mg-dbx objects in multi-threaded applications:

    // Use:
    var <global> = new mglobal(<db>, <global>);
    // Instead of:
    var <global> = <db>.mglobal(<global>);

    // Use:
    var <cursor> = new mcursor(<db>, <global_query>);
    // Instead of:
    var <cursor> = <db>.mglobalquery(<global_query>)

    // Use:
    var <class> = new mclass(<db>, <classmethod>);
    // Instead of:
    var <class> = <db>.classmethod(<classmethod>);

    // Use:
    var <sql> = new mcursor(<db>, <sqlquery>);
    // Instead of:
    var <sql> = <db>.sql(<sqlquery>);

The following scheme illustrates how mg-dbx should be used in threaded Node.js applications.

   const { Worker, isMainThread, parentPort, threadId } = require('worker_threads');

   if (isMainThread) {
      // start the threads
      const worker1 = new Worker(__filename);
      const worker2 = new Worker(__filename);

      // process messages received from threads
      worker1.on('message', (message) => {
         console.log(message);
      });
      worker2.on('message', (message) => {
         console.log(message);
      });
   } else {
      var dbx = require('mg-dbx').dbx;
      // And as required ...
      var mglobal = require('mg-dbx').mglobal;
      var mcursor = require('mg-dbx').mcursor;
      var mclass = require('mg-dbx').mclass;

      var db = new dbx();
      db.open(<parameters>);

      var global = new mglobal(db, <global>);

      // do some work

      var result = db.close();
      // tell the parent that we're done
      parentPort.postMessage("threadId=" + threadId + " Done");
   }

The Event Log

mg-dbx provides an Event Log facility for recording errors in a physical file and, as an aid to debugging, recording the mg-dbx functions called by the application. This Log facility can also be used by Node.js applications.

To use this facility, the Event Log file must be specified using the following function:

   db.setloglevel(<log_file>, <Log_level>, <log_filter>);

Where:

  • log_file: The name (and path to) the log file you wish to use. The default is c:/temp/mg-dbx.log (or /tmp/mg-dbx.log under UNIX).
  • log_level: A set of characters to include one or more of the following:
    • e - Log error conditions.
    • f - Log all mg-dbx function calls (function name and arguments).
    • t - Log the request data buffers to be transmitted from mg-dbx to the DB Server.
  • log_filter: A comma-separated list of functions that you wish the log directive to be active for. This should be left empty to activate the log for all functions.

Examples:

  db.setloglevel("c:/temp/mg-dbx.log", "e", "");
  db.setloglevel("/tmp/mg-dbx.log", "ft", "dbx::set,mglobal::set,mcursor::execute");

Node.js applications can write their own messages to the Event Log using the following function:

  db.logmessage(<message>, <title>);

Logging can be switched off by calling the setloglevel function without specifying a log level. For example:

  db.setloglevel("c:/temp/mg-dbx.log");

License

Copyright (c) 2018-2020 M/Gateway Developments Ltd, Surrey UK.
All rights reserved.

http://www.mgateway.com
Email: cmunt@mgateway.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Release Notes

v1.0.3 (28 June 2019)

  • Initial Release

v1.0.4 (7 September 2019)

  • Allow a global to be registered with a fixed leading key (i.e. leading fixed subscripts).
  • Introduce a method to reset a global name (and any associated fixed keys).

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!.

v1.2.6 (10 October 2019)

  • Introduce support for direct access to InterSystems IRIS/Cache classes.
  • Extend cursor based data retrieval to include an option for generating a global directory listing.
  • Introduce a method to report and (optionally change) the current working global directory (or Namespace).
  • Correct a fault that led to the timeout occasionally not being honoured in the lock() method.
  • Correct a fault that led to Node.js exceptions not being processed correctly.

v1.3.7 (1 November 2019)

  • Introduce support for direct access to InterSystems SQL and MGSQL.
  • Correct a fault in the InterSystems Cache/IRIS API to globals that resulted in failures - notably in cases where there was a mix of string and numeric data in the global records.

v1.3.8 (14 November 2019)

  • Correct a fault in the Global Increment method.
  • Correct a fault that resulted in query.next() and query.previous() loops not terminating properly (with null) under YottaDB. This fault affected YottaDB releases after 1.22
  • Modify the version() method so that it returns the version of YottaDB rather than the version of the underlying GT.M engine.

v1.3.9 (26 February 2020)

  • Verify that mg-dbx will build and work with Node.js v13.x.x.
  • Suppress a number of benign 'cast-function-type' compiler warnings when building on the Raspberry Pi.

v1.3.9a (21 April 2020)

  • Verify that mg-dbx will build and work with Node.js v14.x.x.

v1.4.10 (6 May 2020)

  • Introduce support for Node.js/V8 worker threads (for Node.js v12.x.x. and later).
    • See the section on 'Using Node.js/V8 worker threads'.
  • Introduce support for the M Merge command.
  • Correct a fault in the mcursor 'Reset' method.

v1.4.11 (14 May 2020)

  • Introduce a scheme for transmitting binary data between Node.js and the database.
  • Correct a fault that led to some calls failing with incorrect data types after calls to the mglobal::increment method.
  • mg-dbx will now pass arguments to YottaDB functions as ydb_string_t types and not ydb_char_t. Modify your YottaDB function interface file accordingly. See the section on 'Installing the M support routines'.

v2.0.12 (25 May 2020)

  • Introduce the option to connect to a database over the network.
  • Remove the 32K limit on the volume of data that can be sent to the database via the mg-dbx methods.
  • Correct a fault that led to the failure of asynchronous calls to the dbx::function and mglobal::previous methods.

v2.0.13 (8 June 2020)

  • Correct a fault in the processing of InterSystems Object References (orefs).
    • This fault only affected applications using API-based connectivity to the database (as opposed to network-based connectivity).
    • The fault could result in Node.js throwing 'Heap Corruption' errors after creating an instance of an InterSystems Object.

v2.0.14 (17 June 2020)

  • Extend the processing of InterSystems Object References (orefs) to cater for instances of an object embedded as a property in other objects. For example, consider two classes: Patient and Doctor where an instance of a Doctor may be embedded in a Patient record (On the Server: "Property MyDoctor As Doctor"). And on the Node.js side...

      var patient = db.classmethod("User.Patient", "%OpenId", patient_id);
      var doctor = patient.getproperty("MyDoctor");
      var doctor_name = doctor.getproperty("Name");
    
  • Correct a fault in the processing of output values returned from YottaDB functions that led to output string values not being terminated correctly. The result being unexpected characters appended to function outputs.

v2.0.15 (22 June 2020)

  • Correct a fault that could lead to fatal error conditions when creating new JS objects in multithreaded Node.js applications (i.e. when using Node.js/V8 worker threads).

v2.0.16 (8 July 2020)

  • Correct a fault that could lead to mg-dbx incorrectly reporting 'Database not open' errors when connecting to YottaDB via its API in multithreaded Node.js applications.

v2.1.17 (1 August 2020)

  • Introduce a log facility to record error conditions and run-time information to assist with debugging.
  • Change the default for the multihtreaded property to be true. This can be set to false (in the open() method) if you are sure that your application does not use Node.js/V8 threading and does not call mg-dbx functionality asynchronously. If in doubt, it is safer to leave this property set to true.
  • A number of faults related to the use of mg-dbx functionality in Node.js/v8 worker threads have been corrected. In particular, it was noticed that callback functions were not being fired correctly for some asynchronous invocations of mg-dbx methods.

v2.1.18 (12 August 2020)

  • Correct a fault that could lead to unpredictable behaviour and failures if more than one V8 worker thread concurrently requested a global directory listing.
    • For example: query = new cursor(db, {global: ""}, {globaldirectory: true});
  • For SQL SELECT queries, return the column names and their associated data types.
    • This metadata is presented as a columns array within the object returned from the SQL Execute method.
    • The columns array is created in SELECT order.
  • Attempt to capture Windows OS exceptions in the event log.
    • The default event log is c:\temp\mg-dbx.log under Windows and /tmp/mg-dbx.log under UNIX.

v2.1.19 (15 August 2020)

  • Update the internal UNIX library names for InterSystems IRIS and Cache.
    • For information, the Cache library was renamed from libcache to libisccache and the IRIS library from libirisdb to libiscirisdb
    • This change does not affect Windows platforms.
Category
Developer Environment
Works with
InterSystems IRISInterSystems IRIS for HealthCachéEnsemble
Tags
Info
Version
2.1.19
Last updated
2020-10-07
Repository
Open
Documentation
Open
License
Link