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.
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.
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.
- 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.
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\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:
To start your application, simply run:
And go to http://localhost:3000/ in your web browser to access it.
You should be able to see something like this:
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.
- 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.
- the form has 3 properties. An ID so that other elements can reference it, the action which defines what action will be triggered and the HTTP method used to trigger that action.
- you should end up with a button like this on your main page:
- 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
GETrequest 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
iplinfoalong 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
- PUG template engine has conditional statements built in, so we can display additional content based on the existence of a variable
- in our case, if we pass
iplinfowhen rendering the
indexpage, then the Output paragraph will be rendered as well.
- 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/cliinstalled, let's create a folder named
servicesthat will store our application services, and there create a new file called
mainframe.jswhere we build our function that will issue the Console command.
- we’ve built a
Mainframeobject 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
- 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
sessionbased on the connection details passed before
- we hard coded the command to display IPL information
- we call Zowe’s API to issue the TSO command, passing the needed parameters
- and finally, we parse the output and return it.
Let’s do a quick restructure of our application.
- we add a
controllersfolder, to hold all of our actions for the front-end. The controllers will call the
services, and in turn, the router in
index.jswill call the controllers.
- here we create an
mfController.jswith the following content:
- as you can see, we require our mainframe service file, and instantiate the Mainframe object we defined there
- we create the
getIplInfofunction that is similar to what we had in the
index.jsfile, and export it
Now we can go to our
index.js file, require this specific controller, and use it there.
index.jslooks cleaner 😊.
- finally, since we get back a list of strings, let’s add a loop to our
index.pugfile, to improve the output display.
4. Personal touches
- change the title in
mfController.jsfrom Express to z/OS IPL INFO
index.pugchanged the welcome message
5. Final output
And when we click the button, we get this:
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.
- Go to https://www.heroku.com/ and Sign Up with your Github account (it’s free).
- After you log in, choose to create a new application
- give it a name
- select a region
- then click
- In the
Deploypage, choose to deploy from GitHub
You will then have to select the repository from your GitHub account, that you want to deploy to Heroku
HINT: if you click the
Searchbutton without typing in any repo-name, it will list all of your repositories.
when you found your repo, click
4. Select which branch you want to deploy (it defaults to
master) and click
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.