Mapping Your Mainframe Data for Access From Bluemix

5 min read

Mapping Your Mainframe Data for Access From Bluemix

This is part 3 of a five-part series on accessing mainframe data from your Bluemix applications.


If you have not yet read part 1 and part 2 of this series, please review them before proceeding further.

At this point, you should have already installed the Rocket Mainframe Data Service on your mainframe and have it up and running. Next, you need to determine what data you would like to make available for consumption from Bluemix. This is an important part of enabling access to data on the mainframe. To comply with your company’s data access policies, we recommend that you consult with your database administrator (or system programmer) before completing this step. In fact, your database administrator (or system programmer) may want to complete this step his or herself.

Creating Virtual Source Library and Collection

In the “Getting Started” guide, you will find a link to the “Studio” installer. In “Studio,” you create the virtual tables or collections that enable access to data on the mainframe using SQL and/or MongoDB APIs. A key feature of this is that the data needs to be mapped only once. After the initial mapping is done, it can be used by all supported protocols.

So, let’s get started…

Note: The SMF data comes pre-mapped with the product in a set of virtual tables. If you only need to consume SMF records in your app, you can skip this step.

To begin, download the “Studio” installer on your Windows machine and install the “Studio.” It is a very straightforward process, so I won’t go into the details of the installation itself.

Next, you need to map the data by completing the following steps:

  • Identify the source libraries

  • Create tables and/or collection using the source libraries

  • Generate necessary SQL and/or JavaScript to review the data being returned. Tweak as necessary.

We will review these three steps briefly. The best way to approach this is to view the instructional videos that we have provided as part of this article. It will walk you through these three steps. For the purposes of this article, we will map a VSAM file into a virtual collection that be accessed using MongoDB APIs.

Note: It is important to launch the Studio in the administrator mode in windows. You can right click Studio, and select Run as administrator.

Identify the source libraries

virtual source library is a reference to a library that is on the mainframe and which contains the information required to virtualize the source data.

To identify the source library, you must first establish a connection to the mainframe data service on a special provisioning and administration port.

To establish the connection to the service, complete the following:

  • From the Studio menu, select Window->Open Perspective->Rocket Data.

  • On the Server tab, click Set Server.

  • In the Set Server dialog box, complete the following fields:Host: Enter the TCP/IP host name or IP address of the mainframe system on which server is deployed.Port: Enter the port number that the server is using. The default is 1200.Userid: Enter the mainframe user ID.User Password: Enter the password associated with the mainframe user ID.


  • Click OK.

Now that you are connected to the server, you can begin mapping the VSAM data for consumption by cloud or mobile applications. For VSAM and sequential files on the mainframe, you will need to specify a PDS or PDS/E when defining the source library.

  • On the Server tab, under Admin, expand Source Libraries.

  • Right click Create Virtual Source Library, and select Create Virtual Source Library.

  • From the list of wizards, select the type of data to reference, Data Set (in our case), and then click Next.

  • Enter a name for the source library, an optional description for the source library and the name of the mainframe data set that the source library references.

  • Click Finish. The new source library is displayed in the Source Libraries folder.

That’s it! It’s not rocket science 🙂 Next, let’s create a virtual collection to enable access to that data.

Create a collection for the source library

You need the VSAM cluster name handy for this step.

  • On the Server tab, verify that you are connected to the correct Data Service server.

  • Expand Admin → Source Libraries and verify that the required source libraries exist.

  • Expand NoSQL and the database node from which you want to create the virtual collection.

  • Right-click the database, and select Create Virtual Collection.

  • Under Wizards, select the wizard to use, and then click Next.

  • Provide a name, a target dataset (where the mapping information will be saved), an optional description. Optionally, you can also define how VAR fields should be handled. Click Next.

  • Complete the source library fields (the source library and library member) and click Next.

  • Complete the data layout fields (source, start field and end field) and click Next.

  • Optionally, expand redefine to modify the default table redefines and click Next.

  • Complete the fields for cluster name, post-read exit name, pre-write exit name, alternate indexes and click Next. If you would like to enable MapReduce parallelism setting in the server (for faster read access to the underlying data), please click on Advanced on specify the thread count.

  • Click Finish.

Yes, you are done. That seems like a lot of steps, but, it literally takes under a minute to do all of this as the Studio will prompt you or pre-fill the necessary information. You (or your database administrator) can expect to spend more time verifying data layout fields to ensure they are mapped correctly and also to exclude certain fields that shouldn’t be accessed from Bluemix applications.

Generating JavaScript for your data access program

To access mainframe data using MongoDB APIs, you can use the nifty JavaScript generation tool in the Studio.

  • On the Servers tab, right-click the collection for which you want to generate the MongoDB query, then select Generate Query. The generated JavaScript is displayed in the generate.js view.

  • If necessary, modify the query in the results view.

  • To execute the query from the view, highlight the query and press F5. You can view the results in the query results view.

Next, we will build the Bluemix application that will consume this data (the moment you have been waiting for). Stay tuned…

Be the first to hear about news, product updates, and innovation from IBM Cloud