Creating a Flutter App to Interact with z/OS via Zowe

Mehmet Alp Sümer
Dec 14, 2019 · 8 min read

z/OS? What is that?

If you are a fairly young engineer or developer like me, it is most likely you have no idea what z/OS or z System is, even though you interact with it probably every day so many times. (Learn about mainframes in detail: https://www.ibm.com/it-infrastructure/z/education/what-is-a-mainframe)

IBM Z 15
IBM Z 15
IBM z15, the current version of the Z systems

Well, don’t worry! It has been barely 2–3 months since first I got to know about IBM Z systems or traditionally known as mainframes — and about z/OS (operating system for Z) naturally. In fact, besides its super powerful computing capabilities, I was really amazed how mainframes pioneered the newest technologies we all are familiar with today, such as virtualization or how mainframes are backward compatible to its descendants back to 60s, and much more other things.

In this story, I will share how easy it is to interact with z/OS using Zowe’s components.

Why Flutter?

I have used Flutter, but you can totally use any other technology for your client app. I chose it only because I was recently playing with Flutter and wanted to target this app on mobile devices. And if you haven’t heard about Flutter, it is a quite new technology by Google, that you can build Android, iOS and web applications with a single codebase. (See more about Flutter: https://flutter.dev/)

About Zowe

Zowe is an open source project that aims to serve Z system technologies to all of the community. Traditionally, Z system users interact with the operating system with TN3270 (T stands for Telnet).

TN3270 initial screen

This console is very efficient if you use it for years and have your own flow with your own key macros, and it can be really easy to get stuff done rapidly, even it seems very ancient compared to tools we have on this day for young developers. If you and me, as the new generation of engineers/developers see that, we could be discouraged and overwhelmed by the complexity of this console. Eventually, mainframes’ roots go back decades from today, where everything was so different. It makes sense when you think about websites in 2000s and now, it is noticable that there is a huge change in user behaviour and requests. That is why there was a need for a project like Zowe!

Zowe allows interaction with z/OS with modern interfaces — for example Zowe Desktop is a web application that is similar to Window’s desktop environment.

Let’s compare TN3270 and Zowe interfaces, doing the same task that is displaying data sets with the qualifier of my username (z40640).

Display data sets on TN3270
Display data sets on Zowe

Now… Which one do you feel more familiar with? That’s not even all about listing data sets. On Zowe, with a single click you can display the content of a data set and start editing quickly, as for TN3270 you have to tab through the data set and execute the option you want and start editing on ISPF editor. ISPF editor is a very strong editor, but like TN3270, it has a steep learning curve. For Zowe, it is very similar to a standard text editor that you use on a daily basis.

Another thing for data set is about programs you load into z/OS. I don’t know about you, but I love to use Visual Studio Code. It is very flexible and fast code environment for me. You can develop with whatever technology you desire with the right extensions. And guess what..? Zowe has a VSCode extension that stands there! You can browse your data set — let’s consider a Java code — and edit it. It is also applicable for Job Control Language (JCL). You can write your Jobs and submit them through a single editor with syntax highlighting or autocomplete or whatever you can expect from VSCode.

How does Zowe do all of these?

Zowe has 4 main components. These are: Zowe CLI, z/OS Services, Zowe Application Framework and API Mediation Layer. The last one is the one which we will be using to create the client app. Let’s see how this component is described on Zowe’s official website. (https://docs.zowe.org/stable/getting-started/overview.html#api-mediation-layer)

Zowe 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. Base Zowe provides core services for working with MVS Data Sets, JES, as well as working with z/OSMF REST APIs. The API Mediation Layer also provides a framework for Single Sign On (SSO).

REST APIs! Finally something we are familiar with (I hope so). This basically means, we can make a HTTP GET request to a data set endpoint to get a list of them, or make a HTTP POST request to create one, and so on…

API Endpoints

Above we mentioned of an example for the data set, but how do we know endpoints for APIs? In this matter, API Catalog on Zowe Desktop Application got you covered. There, you can launch Swagger UI to see endpoints and paths, what each request takes as parameters and what they do return.

API Catalog on Zowe Desktop

Building the App

Now that we know that we can interact with z/OS through REST APIs, there is nothing that can hold us start building our app! Except…you probably don’t have a z15 sitting in your next room, right? Once again, don’t worry. Because IBM provides trial access for Open Source Development.

You can register with this link: https://www-01.ibm.com/events/wwe/ast/mtm/zowe.nsf/enrollall?openform. After registering you will receive a mail with your credentials and some easy to follow instructions. Also I will leave a Slack channel on the bottom that you can communicate with the community in case you need any help. You can also leave a comment, ask anything you need!

General Structure

I will not be going step by step in every piece of code I write, rather talk about the general procedures, so that you can easily implement this with any technology you want (no doubt you already can with REST API provided, but just in case!).

GitHub repo for the whole app can be found here: https://github.com/mehmetalpsumer/zowe-flutter

For the file structure in the project, I created models to represent responses by Zowe API, services to connect and make request from endpoints, and views to display screens. Also, for the state management I used provider package.

The first thing we must go through is authentication. To have access to these endpoints, of course we need to let the system know that we have access to the system. The simplest way to authenticate ourselves is using token that is generated by our username and password. For Auth API documentation, see here: https://github.com/zowe/zlux/wiki/Authentication-&-Authorization-API.

Also before starting, I want to mention is how I stored API endpoints (provided by the trial machine) since each service uses different one. In the lib directory I created a file called env.dart. This stores static values of endpoints for production or development. It may be irrelevant to this example, but it is a good habit to have both I suppose.

Storing Zowe API endpoints
api.service that stores Web client to use when making requests

Authentication

To authenticate our request to APIs, the system expect us to have a Authentication key in the HTTP request we make. This key is base64 encoded version of the username:password string. For example, if my ID is Z4040 and password 1234, I need to attach base64 encoded version of Z4040:1234.

Login screen

Let’s create a model called user and create a service auth, then we will store a static version of our user to access this easily from anywhere. We will also store our token in the user model, however it may be more convenient to calculate a function that is executed for each request.

User model

As we saw in the documentation, we POST our JSON including username and password. And if we are successfully authenticated, response will include { success: true }. Then we can create User instance with our token that we will attach to our requests. Token is simply created by converting string to list of bytes and encode it to base64. All of the conversion tools are provided by Dart.

POST request to auth endpoint

Getting the content of a data set

Now that we have implemented authentication, we can start interacting with z/OS. As the only example, let’s briefly see how we get our data sets. As you remember we would create models to receive responses with style! (I must admit, it is not the most stylish for this example to have a single field called records though…)

Data set content model

This is basically a class that stores contents of a data set as string. And if you remember from the API catalog, we need to make a HTTP GET request to path /api/v1/datasets/$dataSetName/content. To get contents of Z40640.JCL, the full path would be: https://192.86.32.67:8547/api/v1/datasets/Z40640.JCL/content.

Let’s not forget to add our token to the request, as seen below, otherwise you’ll get a 401 not authorized response.

GET request to data set content

See how we added ‘Authorization’ key to HTTP request header. Also how we leveraged fromJson in our model. It makes things pretty straight forward and easy to read.

Conclusion

I know this story has been touching several topics and not with so many details, but I do hope you have now heard about system Z or mainframes and willing to search more about them, what z/OS is and steps IBM is taking to meet open source with mainframe systems and make the new generation get to know and love their systems.

Now you can play with Zowe to make your own applications with your favorite development stack or you can go contribute to the Zowe project.

Zowe website: https://www.zowe.org/

Slack channel: https://slack.openmainframeproject.org/

GitHub repo: https://github.com/mehmetalpsumer/zowe-flutter

Please do not hesitate to ask anything below, or please leave a comment if there be any mistakes or a room for improvements. Thanks for your time!

Zowe

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.

Mehmet Alp Sümer

Written by

Zowe

Zowe

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