Node.js: installation and connection test for use with Cache
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).
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:
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é.