You are currently on IBM Systems Media’s archival website. Click here to view our new website.
i For Business Event Logo

Bookmark and Share

Recent Posts

Cleared for Takeoff With Node.js on IBM i

November 21, 2017

OK, I’m done with flight-related puns for now, I promise! In my last blog entry, we showed you how to expose web services using the Integrated Web Services (IWS) server on IBM i. As you know, once a capability is exposed as a web service, it can be consumed from virtually anywhere. But, what if you want to run and host your solution entirely on IBM i? Today, I will show you how to use Node.js to do just that.

In today’s sample, we start with the same “Flight400” application (hence the bad airline pun). To review, this is a green-screen application built around a fictional airline ticketing system.


Today’s objective is simple: to create a web interface for our ticketing system that runs on IBM i. This short demo was written by my esteemed colleague Tony Cairns.

Getting Started
Before you get started, you’ll want to ensure that you have Node.js installed. I’d suggest Node.js version 6, which is shipped in 5733-OPS option 10. See the 5733-OPS page on developerWorks for more information, or consult The 5733-OPS Installation Guide at the Club Seiden Learning Hall blog (thanks, Josh!).

To set Node.js version 6 as your default version, you can run the following command as a system administrator:

/QOpenSys/QIBM/ProdData/OPS/Node6/bin/ 6

If you are not an administrator, you can run these commands from most shells:

export PATH

These commands will add the Node.js version 6 binaries to your PATH. If you’re not sure what PATH is, see Kevin’s Ramblings.

Once that’s set up, you can verify you are running the right version of the language by running:

node --version

Now, create a directory where you’d like to do your work, ‘cd’ into that directory. Run ‘npm init’ to initialize your Node project (this is optional, but recommended), and then install the Express.js web framework:

npm install express

That’s it! Now you are ready to write some Node.js code to serve up a web page. You’ll also want to talk to RPG code, so you will want to familiarize yourself with the Toolkit APIs we will use in today’s sample.

We start by initializing a few things, like so:


In case you are new to Node.js, here’s a brief explanation of what’s going on in this code snippet. That require() invocation shows us how the Node.js module system works. The “express” module is the Express.js web framework, which can now be accessed through the “express” variable. The “FlightJson400” variable is a module written as part of this application (there will be a flight400/flightjson400.js file in the project’s workspace). We also use a package called “body-parser” and set some options to help use handle HTTP POST data when it comes in. Lastly, we use an instance of the Express.js Router capability to handle various HTTP routes (we’ll take a look at one later).

Web Services are an Important Piece
In this exercise, we’re just building a simple web page. So, why are web services needed? Simply put, they enable the IBM i to handle calls from the client’s browser, thereby enabling rich web content. Let’s look at a simple example. Here is the booking screen of our application.


The user is on the booking screen and types the letter ‘H’. Javascript code running in the web browser sends a request to IBM i to get a list of cities, filters the resultant list, and immediately provides a user-friendly list of cities to choose from:


In the green-screen form of the application, as you might guess, you’d get at this list by use of the F4 key.

Connecting the Pieces
Let’s take a look at how this piece fits together. When the client-side code wants a list of cities, it sends a request to the URL http://<hostname>/flight400/api/all/from. On the IBM i, that gets routed to the following function (thanks to the Express.js Router):


Note that http://<hostname>/flight400/api/all/to, which lists destination cities, would also get routed to this function (the last token in the URL ends up in the “fromTo” variable. Because the RPG calls are encapsulated in a separate module (in the flight400 variable), the web service code is relatively clean. In just a couple lines, it calls the RPG code and transforms the output to JSON.

For education’s sake, let’s follow that function down to where it calls RPG. Note that the “xt” variable contains the Toolbox API’s mentioned earlier. In the comment, you can see the RPG declaration (the RPG application is dated, as you can see by the fixed-form syntax). Once you know the inputs and outputs of the RPG code, it’s pretty easy to call from Node.js!


This simple web page uses a number of such RPG calls throughout the booking process to figure out flights, times, prices, etc.


At the time of this writing, this application is currently being hosted here by the Young i Professionals group. Check out the API tab for more details behind the REST APIs.

Join Us at the Water Cooler!
I focused on a few parts of this sample application that I found interesting. You may need to see the entire program to understand how it all fits together. Thankfully, all of the source code behind today’s example is available here. It’s part of a KrengelTech-owned repository, which brands itself as “The IBM i Water Cooler.” If you visit the project (here) you will find several useful examples from Tony Cairns, Aaron Bartell, and others. For instance, you can learn how to do things like:
  • Create a websocket-based chat program
  • Work with a remote keyed data queue
  • Use Express.js
  • Use Hapi.js for IBM i authentication
  • Do database connection pooling properly
  • Build a simple web page driven by Db2 for i database tables
Don’t be shy! As you explore the capabilities of Node.js on IBM i, come back to the water cooler and share some of your creation!

Closing Thoughts
Last week, I talked about creating web services with the Integrated Web Services server. In this post, I talk about using Node.js to do the same. There remain countless other ways, like the WEBSRVUTL package that I’ve mentioned in the past. Similarly, there are numerous ways to spin up a web server and host a web page (some new, some old). While choosing the right technology is sometimes difficult, it’s important to have several choices. After all, business needs (and constraints) can vary greatly from one scenario to the next. Open source technology will continue to expand our options. Whether you’re looking to add modern flair to existing applications or write new ones, you have more tools in your proverbial toolbox than ever before!

Posted November 21, 2017| Permalink