Installing ewdGateway2 for Caché + Windows

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:

EWD

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:

 w $$version^%zewdAPI()

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:

 http://gradvs1.mgateway.com/download/ewdMgr.zip

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

Install Node.js

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:

  node -v

You should get the response:

   v0.6.21-pre

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:

 
d compileAll^%zewdAPI("ewdMgr",,"ewd")

Note those 2 commas!

Start ewdGateway2

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:

   http://127.0.0.1:8080/ewd/ewdMgr/index.ewd

The application should burst into life!

That’s it! You now have ewdGateway2 successfully running.

Notes:

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.

 

 

 

 

 

 

 

 

 

 

 

 

 

Advertisements

6 comments

  1. Just a quick note: if you’re already using EWD, you’ll need to upgrade to build 953 or later. Earlier versions won’t work correctly with ewdGateway2

  2. Jay Mandla · · Reply

    Hi Rob,

    Thanks for the tutorial.

    Unfortunately I seem to have a problem at point 17.
    cd\node
    node ewdStart-cache

    Gives me the following error:
    C:\Windows\System32>cd\node

    C:\node>node ewdStart-cache

    module.js:337
    throw new Error(“Cannot find module ‘” + request + “‘”);
    ^
    Error: Cannot find module ‘C:\node\ewdStart-cache’
    at Function._resolveFilename (module.js:337:11)
    at Function._load (module.js:279:25)
    at Array.0 (module.js:484:10)
    at EventEmitter._tickCallback (node.js:190:38)

    C:\node>

    I tried a restart of the PC (the guru’s problem solver!) but the problem has persisted.

    As I am new to node.js I am unsure where to go from here.

    Thanks in advance and Regards,

    Jay Mandla

  3. Jay Mandla · · Reply

    Additional Info:

    Cache Version
    Cache for Windows (x86-32) 2013.1 (Build 446)

    Windows 7 Professional 32bit.

  4. Jay Mandla · · Reply

    Hi Rob,

    OK, I got it installed!!

    Thanks for the great tutorial.

    Some of the folder paths have changed since this was 1st published.

    Regards,

    Jay Mandla

  5. Testing Environmnet · · Reply

    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)

    Please Explain those steps in your website how to do it ?
    in GITHUB ewd.js-master these file name only availabale ….
    in cache how to use this file please explain

    1. Actually I ought to remove this posting as what it describes has been deprecated, having been superseded by EWD.js

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: