The following is a quick tutorial for users of Caché, explaining how to install ewdGateway2: the Node.js platform for EWD.
This tutorial assumes you’re using Windows 7 (64 bit) along with Caché 2012.1 or later (earlier versions of Caché don’t include the Node.js interface module). If your set-up is different, you may need to adjust some of the steps – mostly this will involve modifying the file paths.
So here goes:
1) Download EWD from http://www.mgateway.com. You’ll need to click on the tabs marked EWD/Download EWD/EWD for Caché, then fill out the form.
2) Expand the downloaded zewdxxx.zip file and find the file inside it named zewd.xml. Copy this to the c:/InterSystems/Cache/Mgr directory (or wherever your Caché Mgr directory resides)
3) Start a Cache Terminal session and type:
zn "%sys" d $system.OBJ.Load("zewd.xml")
You’ve now installed EWD. You can test it’s OK by running the function:
You should be told the build number of the version of EWD you just installed (eg 953).
Create Directories you’ll Need for EWD applications and ewdGateway2
4) Now create the following directories (initially empty):
c:\ewdapps c:\ewdapps\ewdMgr c:\node c:\node\www c:\node\www\js c:\node\www\ewd\ewdMgr
Get the ewdMgr Application
5) Download the pre-built EWD application named ewdMgr from the M/Gateway web site. This is a useful pre-written EWD application for testing your EWD and ewdGateway2 configuration. Use the URL:
6) Expand the downloaded zip file and copy its contents into the c:\ewdapps\ewdMgr directory
7) Copy the contents of c:\ewdapps\ewdMgr\resources into the c:\node\www\ewd\ewdMgr directory
8) Copy the file c:\ewdapps\ewdMgr\resources\ icn_help_blue.gif into the c:\node\www\js directory
9) Now delete the c:\ewdapps\ewdMgr\resources directory
10) Next we’ll download and install Node.js. If you’re using Caché 2012.x, you’ll need to use Node.js version 0.6.x, so do the following:
- go to http://nodejs.org
- select Downloads
- Select Other Info / Other Releases
- Select v0.6.21
- select x64/
- Click on node.msi
- When it’s downloaded completely, double-click it to invoke the installer. Accept the defaults and let it run to completion.
11) Test that the Node.js installation worked successfully by opening a Windows Command Prompt window and type:
You should get the response:
Install WebSockets and ewdGateway2
12) In the Windows Command Prompt window, type the following:
cd \node npm install socket.io npm install ewdgateway2
13) In the directory c:\intersystems\cache\bin\ you should find a file named cache061.node. Copy this file to the c:\Program Files (x86)\nodejs directory and rename it to: cache.node
14) In the directory c:\node\node_modules\ewdgateway2\examples\ you’ll find a file named ewdStart-cache.js. Copy this to the to c:\node directory.
Configure EWD for use with Node.js and ewdGateway2
15) Go back to the Caché Terminal and type:
zn "user" d configure^%zewdNode
This will have created the ^zewd Global as follows:
^zewd("config","RootURL","ewd")="/ewd" ^zewd("config","applicationRootPath")="c:\ewdapps" "frontEndTechnology")="ewd" ^zewd("config","jsScriptPath","ewd","mode")="fixed" "outputPath")="c:\node\www\js" "path")="/js/"
Compile the ewdMgr Application
16) In the Caché Terminal, type:
Note those 2 commas!
17) Go back to the Windows Command Prompt window and type:
cd \node node ewdStart-cache
Run the ewdMgr Application in a browser
18) Start a browser (eg Chrome) on your Windows machine and enter the URL:
The application should burst into life!
That’s it! You now have ewdGateway2 successfully running.
ewdGateway2 is configured by the file ewdStart-cache.js (You can rename this if you wish, by the way!)
The parameters should be self-explanatory in the main and I’ll document them fully very soon. However the one to note is the poolSize parameter, which determines how many worker child processes are created by ewdGateway2. Each one consumes a Caché license. A further background Caché process is jobbed off during the startup phase: this is required for WebSockets support and be aware that this process will also consume a Caché license. Feel free to modify the poolSize (it must be at least 1), but make sure you don’t exceed your total number of available Caché licenses!
Some early experiments I carried out suggested that maximum throughput was achieved with ewdGateway2 when the poolSize equalled the number of available CPU cores. I’ll be interested to hear users’ experiences and see if this remains true in real-world situations.
You may need to adjust some of the paths in the instructions above. You’ll also need to check the paths in the ewdGateway2 startup file: ewdStart-cache.js. Adjust them appropriately as required until ewdGateway2 starts up without reporting any errors.
To stop ewdGateway2, just type CTRL & C.
It is possible to run ewdGateway2 as a service. You’ll need to adjust some settings in the startup parameter file, in particular set silentStart to true, and set the logTo parameter to file.
The amount of logging/tracing information is determined by the traceLevel parameter. A value of 0 turns off all logging. Maximum information is provided if it is set to 3.
In future articles I’ll explain how you can dynamically change the run-time parameters and also how to use WebSockets with EWD applications running via ewdGateway2.