Quickly Build a Mainframe Web App with ExpressJS and Zowe CLI

Alex Dumitru
Dec 9, 2019 · 8 min read

Modern mainframe developers want to have the possibility to quickly build engaging web front ends or entire applications using modern tools and frameworks. They have a plethora to choose from, but I want show you a quick way using ExpressJS, because of it’s simplicity and soft learning curve and Zowe CLI.

Background

Zowe is an open source project that hosts technologies benefiting all members of the Z community (Integrated Software Vendors, System Integrators and z/OS consumers). Zowe comes with a set of APIs and OS capabilities that applications build on and also includes some applications out of the box.

Zowe consists of the following main components:

Zowe Application Framework: A web user interface (UI) that provides a virtual desktop containing a number of apps allowing access to z/OS function.

API Mediation Layer: Provides a gateway that acts as a reverse proxy for z/OS services, together with a catalog of REST APIs and a dynamic discovery capability.

Zowe CLI: Provides a command-line interface that lets you interact with the mainframe remotely. It provides a set of utilities and services for application developers that want to become efficient in supporting and building z/OS applications quickly.

What I find really interesting is the fact that the CLI component offers a *set of utilities and services* that can help us build z/OS applications quickly. And this is the aspect I want to explore here.

Zowe CLI

The name says it all. It’s a CLI application that is meant to give users an off-platform way to interact with the mainframe. Since I am using this almost on a daily basis, I can say this aspect works great.

In more technical terms, Zowe CLI is a Node.js application written in TypeScript, that is using z/OS REST APIs to communicate with the mainframe.

For a full set of capabilities, please see the docs.

With that being said, I want to draw attention to the way the application is structured. If we check the github repository, we notice that each command group is split in two parts (example here).

- A CLI part:
that contains the front-end of the application (what we see in the console when we use it)

- and an API part:
that holds the method implementations for each command.

This is the part that we want to explore!

Without further ado, let’s jump right in, and start building our Mainframe Web Application.

Pre-requisites

Since this is a Node.js application, we need of course Node.js installed.
Go ahead to https://nodejs.org/en/ and install the LTS version for your OS. Make sure you also install npm in the process.

Building our application

Let’s create a folder that will contain the source code, and navigate to it:

$ mkdir zowe-webapp
$ cd zowe-webapp

Now let’s build our application skeleton. For that, I’ve chosen ExpressJS as my web framework.

$ npx express-generator --view=pug

npx comes pre-installed with Node.js v 8.2.0 or higher. If you don’t have it, please follow this link to install and use express-generator.

I am using Pug as my HTML template engine, but ExpressJS knows how to work with any number of them. If you are familiar with another one, feel free to use it. Full list here.

Output should look like this:

npx: installed 10 in 2.661s
destination is not empty, continue? [y/N] y

create : public\
create : public\javascripts\
create : public\images\
create : public\stylesheets\
create : public\stylesheets\style.css
create : routes\
create : routes\index.js
create : routes\users.js
create : views\
create : views\error.pug
create : views\index.pug
create : views\layout.pug
create : app.js
create : package.json
create : bin\
create : bin\www

run the app:
> SET DEBUG=zowe-webapp:* & npm start

You may or may not see a warning regarding the folder not being empty. I had a README.md file from initializing it as a git repository.

After this, you need to install the dependencies:

npm install

To start your application, simply run:

npm start

And go to http://localhost:3000/ in your web browser to access it.
You should be able to see something like this:

Initial landing page

Neat, huh?

Let’s make it a mainframe one!

As a use-case, I will try to keep it simple. Let’s say I want to check the IPL information of the system.

IPL stands for Initial Program Load, and it’s mainframe nomenclature for system boot.

In order to get this information, you need to connect to your 3270 terminal emulator of choice, log in with your mainframe credentials, navigate through the ISPF panels, go to the system console, then issue the command /DISPLAY IPLINFO. Pretty lengthy activity, right?

How about we simplify this task, so that the user only needs to press a button and get this information.

  1. Add a button to request the IPL information

The index.pug page, under views directory, is the one which is displayed by default. Here we add a button and a form element:

  • the button has a type=”submit” property, and a form property that ties is to the form id.
Button added
  • if you click it, you should get a 404 error, because the application is looking for http://localhost:3000/iplinfo? which is not yet defined. Let's fix that.

2. Add the routing

  • when the button is clicked, the forms action is performed, so the application is issuing a GET request on that specific page (/iplinfo). This behavior is defined in index.js.
  • we define a new get() method for the router for that specific URL and inside we render the index page again and pass our iplinfo along with other data

Note that for now we use mocked IPL data, and we will come back to it later in the tutorial

  • in order to conditionally display the additional data, we have to edit again the index.pug
  • now, when we click the button, we should see our mocked data.

You might need to restart your server, in order for the changes to take effect. To do this, type CTRL+C in your terminal, where the server is running, then issue npm start` one more time.

3. Implement access to mainframe

  • to be able to access the mainframe, we want to use Zowe’s CLI programmatic APIs. In order to do that, we need to first install it:
npm install @zowe/cli --save
  • now that we have zowe/cli installed, let's create a folder named services that will store our application services, and there create a new file called mainframe.js where we build our function that will issue the Console command.
  • we’ve built a Mainframe object that takes several parameters when instantiating. Those are used to create the session needed to connect to z/OSMF (mainframe).

host: z/OSMF’s hostname
port: z/OSMF’s port
user: your mainframe username
password: your mainframe password
rejectUnauthorized: this value disables certificate validation. Since we don’t use a certificate, we hard code it to false

  • then we have a method that takes one argument, account, needed to run the TSO command. There are more parameters for the TSO command, but the rest have some default values, which we will take them as they are for now.

account: the account number that is issued to you when your mainframe account is created

  • inside this method we create a session based on the connection details passed before

Let’s do a quick restructure of our application.

  • we add a controllers folder, to hold all of our actions for the front-end. The controllers will call the services, and in turn, the router in index.js will call the controllers.
  • as you can see, we require our mainframe service file, and instantiate the Mainframe object we defined there

Now we can go to our index.js file, require this specific controller, and use it there.

  • our index.js looks cleaner 😊.

4. Personal touches

  • change the title in index.js and mfController.js from Express to z/OS IPL INFO

5. Final output

Landing page:

Landing page

And when we click the button, we get this:

Extras

Hosting your web application

There are many hosting services for your web applications, but I’ve found Heroku to be one of the simplest and cheapest (even free) ways to do that.

  1. Go to https://www.heroku.com/ and Sign Up with your Github account (it’s free).

You will then have to select the repository from your GitHub account, that you want to deploy to Heroku

HINT: if you click the Search button without typing in any repo-name, it will list all of your repositories.

when you found your repo, click Connect

4. Select which branch you want to deploy (it defaults to master) and click Deploy Branch.

5. You will be prompted when the deploy is done, and you will be able to see the green status at the end. Click View button to go to your app.

Congratulations! You now you have your very own Mainframe Web Application online.


“Learn more about Zowe at this site; more Zowe blogs here

I personally recommend you to also check my colleague Dan’s blog about building and Electron app using the same principles.

For full source code, please see this GitHub repository.

Zowe for Users

Zowe is the modern open source interface for the mainframe and z/OS. The Zowe blog has how-to’s, tips & tricks and other helpful insights for mainframe devops. Zowe is a project within the Linux Foundation’s Open Mainframe Project (OMP). Download @ Zowe.org.

Alex Dumitru

Written by

Software Developer at Broadcom and Zowe CLI squad member.

Zowe for Users

Zowe is the modern open source interface for the mainframe and z/OS. The Zowe blog has how-to’s, tips & tricks and other helpful insights for mainframe devops. Zowe is a project within the Linux Foundation’s Open Mainframe Project (OMP). Download @ Zowe.org.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade