Article
· Apr 20, 2017 5m read

Node.js: installation and connection test for use with Cache

Full-Stack JavaScript development allows you to create state-of-the-art applications with Caché. With any (web) app you build nowadays, one has to make a lot of architectural decisions and you want to make the right ones. With the Node.js connector available for Caché, you can create a very powerful server side application server, allowing you to use the latest JavaScript technology and frameworks client- and server-side.

With all these new technologies, the most important is to integrate them in the most efficient way and to create a very productive development experience. This article willl get you started step-by-step with Node.js technology.Before you can start developing applications with Node.js for Caché, the first step you need to do is setting up your environment.

To use Node.js with Caché, you need a Node.js (connector) module for Caché.

In each Caché distribution kit, you'll find different versions of this module in the bin directory of Caché, named e.g. cache0100.node, cache0120.node, ... As Node.js versions are updated regularly, I recommend you ask the WRC first to send you the latest version.

Once you received the zip package from the WRC with the latest version, you'll see there are different version numbers inside the bin directory. Picking the right version is not difficult at all, but it is very important to keep in mind these modules are native ones where the Caché platform, architecture (x86 or x64) and the Node.js module version need to match your system. This is a very important step you need to take care of, otherwise the Node.js connector will not work on your system.

Node.js releases come in two flavours: "LTS" and "current" ones. For our applications, I recommend to use always LTS because they are best suited for use with Caché (long-term support and stability).

* If you want all the details about versions, you can find an overview with all releases on the Node.js  website. You'll see this is a long list, but you just need the latest LTS release (with even major version numbers, currently v6.x.x and v4.x.x). Don't use odd numbered major versions, these are current versions not meant for production use and are used to introduce & test the latest JavaScript features in the V8 engine.

Let's give two examples:

  • if you have a Caché 2016.2 running on a Windows x64 system and you want to use Node.js v6.9.4, you'll need the cache610.node file in the bin\winx64 directory.
  • if you have a Caché 2008.2 running on a Windows x86 system and you want to use Node.js v4.8.2, you need the cache421.node file inside the bin\winx86 directory.

I will describe now step-by-step how to download and install Node.js on a Windows x64 system and connect to Caché.

First, start by downloading the latest Node.js LTS release:

Currently this is v6.10.2, just click the green button to download. Install this version on your system with default settings, making sure that the "add to PATH" option is installed/checked:

Now you've installed the Node.js runtime, you can verify if it installed correctly by opening a command prompt and checking the node version:

As you see, I currently have Node.js v6.9.1 installed on my system.

Btw, Node.js is now installed globally in your Windows system (under Program Files).

In your Caché system portal, also first make sure the %Service_CallIn under Security - Services!

When you start a new app with Node.js,  it is common practice to create a new directory first for your app. The first one we need to create is a small Node.js app/script to test the connection between Node.js and Caché. This is the most important step to test first if our Node.js setup is working well before you start developing with other Node.js modules.

Create an empty test directory, e.g. C:\Temp\nodetest

Create a subdirectory node_modules (C:\Temp\nodetest\node_modules)

Put the right cache610.node (from the bin\winx64 directory in the Node.js Caché connector archive) inside this node_modules directory and rename it to cache.node. In all your server-side Node.js apps, the Caché connector needs always to be renamed to cache.node regardless of the Node.js version, architecture and OS it's running on. This makes your applications cross-platform, version- and OS independent!

* Each time you create a new server-side Node.js application, you'll need to add this cache.node module to the node_modules directory. Just copy the instance from your test app to the node_modules directory in the new app on your system. Remember if you install/deploy your server-side app on/to another system, you'll need to check which version you need to install on this system because the Node.js version, system architecture and OS can be different!

Now we just create our nodeTest.js test script inside C:\Temp\nodetest with this code:

// first, load the Cache connector module inside node_modules
let cacheModule = require('cache');
// instantiate a Cache connector object in JavaScript
let db = new cacheModule.Cache();
console.log('Caché database object instance: ', db);

// Open the connection to the Caché database (adjust parameters for your Cache system):
let ok = db.open({
  path: 'C:\\InterSystems\\Cache\\Mgr',
  username: '_SYSTEM',
  password: 'SYS',
  namespace: 'USER'
});

console.log('Open result: ', ok);
console.log('Version: ', db.version());

let d = new Date();
// construct a JavaScript global node object to set a test global in the USER namespace
let node = {
  global: 'nodeTest',
  subscripts: [1],
  data: 'At ' + d.toUTCString() + ': global set from Node.js'
};
// set the global in the database
db.set(node);
// retrieve the global contents back from Cache
let result = db.get(node);
// show it on the console
console.log('Set global ^nodeTest(1) result: ', result);
// close the database connection
db.close();

If you save this script and installed everything correctly, this code should work immediately when you invoke it inside a command prompt:

Congratulations! You've now tested your Node.js application server and connected it successfully to your Caché database.

You'll notice in the test script that the cache.node module contains all functionality you need to access you data in Caché (not only globals, but also functions, classes and SQL!). You'll find the complete documentation about the Caché Node.js module in the online docs under Using Node.js with Caché. Inside the zip archive from WRC, you'll also find a pdf file in the doc directory with all functional details.

You'll also notice that when you start developing with the Caché Node.js module, it provides you with low-level functions to access Caché. 

In a next article, I will show how you can use some Node.js modules to write JavaScript source code to access your Caché globals, functions, classes and SQL queries using a higher level functional abstraction.

Discussion (13)4
Log in or sign up to continue

Hello @Ward De Backer, 

Have you tested this with IRIS?

I am trying to run it using your guide and the documentation (https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=BXJS_connect), and I have this error:

var db = new irisobj.Iris();
         ^

TypeError: irisobj.Iris is not a constructor

I am using node v8.6.0 and iris.800.node.

My code is almost the same as yours:


let irisobj = require('iris');
var db = new irisobj.Iris();
console.log('Intersystems IRIS instance: ', db);

Thanks

BINGO!!

It works like a charm!!

davidreche$ node test.js
Intersystems IRIS instance:  IRIS {}
Open result:  { ok: 1, result: 1, iris_pid: '9511' }
Version:  Node.js Adaptor for InterSystems IRIS: Version: 1.1.161 (CM); IRIS Version: 2019.1 build 284
Set global ^nodeTest(1) result:  { ok: 1,
  global: 'nodeTest',
  subscripts: [ '1' ],
  data: 'At Sun, 21 Oct 2018 19:12:52 GMT: global set from Node.js',
  defined: 1 }
 
Thanks!!

HI Bart, How are you?

I would like to perform some testing with Cache and Node.js.

I am using: Cache for Windows (x86-64) 2017.1.1 (Build 111U_SU) Tue May 23 2017 13:20:26 EDT

and I have

How can I get the right version of the Cache.node? I do not have access tot the WRC and I see a lot of requests on this Community who would like to get the right version.

Dank je wel,

en groeten

to clarify. You have 3 possibilities:
- mg-dbx is a 3rd party product/connector (similar cache<nnnn>.node, iris<nnnn>.node, see next)
- cache<nnnn>.node, iris<nnnn>.node is InterSystems "legacy" node.js adaptor/connector. I don't know how long we will support it in future.
- Native API for node.js. This is InterSystems latest node.js API, recommended for new developments.
  See here: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=PA...