@vision-dbms/connect

A node.js native add-on for the Vision database management system:

var vc=require('@vision-dbms/connect')
var p=vc.v ('2 + 2'). then (r=>console.log (r))

>     4.00


var myObject = {}
var p=vc.v ('JS set: "x" to: 23.7; JS set: "y" to: "Hello, world..."',myObject)
var t=p.then (r=>console.log (myObject))

> { x: 23.7, y: 'Hello, world...' }

Prerequisites

The documentation that follows assumes:

• a reasonably modern LTS version of node (the 8.x track or newer is recommended).
• a version of Vision built from the staging-nodejs-connect branch of Vision's github repository.
• access to one of more Vision databases.

Installation

This node module is available from the npm registry as @vision-dbms/connect:

npm install @vision-dbms/connect

Because @vision-dbms/connect is a native add-on for node, it contains C++ code that must be compiled. npm install does that automatically, provided the required development tools are present on the system. If that system is a Linux or macOS host that has already been used to build Vision (perhaps the staging-nodejs-connect branch mentioned above), the required tools and header files will already be present.

If the system you are using has not been used to build Vision, you may need to install the required development tools and, in the case of Linux systems, some additional system header files. An authoritative list of the tools you need to install can be found in the documentation for node-gyp (note that you do not need to install node-gyp, just its recommendations).

For Linux systems, you may also need to install header files for the system's UUID generator. For Red Hat based systems (RHEL, Centos, etc.), the command you most likely will need to run is:

sudo yum install libuuid-devel

while on Debian based systems (Debian, Ubuntu, etc.), that command will most likely be:

sudo apt install uuid-dev

Use

The Basics

To access @vision-dbms/connect, load it using require:

var vc=require('@vision-dbms/connect')

At its most basic, @vision-dbms/connect gives you the ability to execute Vision expressions using its v method:

var p = vc.v ('2 + 2')

v operates asynchronously, scheduling evaluation of its expression, returning a JavaScript Promise for the output of that expression.

Promises are a major feature and paradigm of JavaScript programming. They are described in great depth on the web (here, for example). What you need to know to get started is that Promises have a then method that takes two functions as arguments, one that will be called with a successfully returned result and one that will be called in case of an error:

var p = vc.v ('2 + 2').then(result=>console.log ('Success: ', result), error=>console.error('Failure: ', error))
> Success:       4.00

A bit of noteworthy magic is happening here. The v method knows where to evaluate its expression courtesy of Vision's session configuration files. Found at common user specific and environment variable (e.g., VcaGlobalSessionsFile, VcaSessionsFile) specified locations, those files are used to create a directory of known servers, services, and process creation templates. By default, @vision-dbms/connect searches that session directory for an entry named NodeEvaluator. It also includes, for its own use in environments that do not define their own session configuration, a very basic NodeEvaluator definition that expects to find a runnable batchvision on the current path:

Connection_Template Begin
Name NodeEvaluator
Program batchvision
Connection_Template End

In a bare environment, if you do nothing else except make sure that batchvision can be found along with a Vision database it can use, the examples documented here should work.