May 27 ’14

Going Mobile: CICS Makes Light Work of Mobile Integration

by Geoff Pirie, Inderpal Singh in Enterprise Tech Journal

The article “New Technologies Help Bridge Gap Between Mobile and the Mainframe” (available at discussed how CICS helps bridge the gap between the mainframe and mobile devices. It also examined the IBM CICS Transaction Server (TS) Feature Pack, which introduces native support for JavaScript Object Notation (JSON) data in CICS. In this article, we go a step further and discuss just how easy it is to create mobile-enabled services from your existing CICS assets, and how these can be rapidly incorporated into an IBM Worklight project for deployment to a multitude of mobile devices.

Feature Pack Recap
The CICS TS Feature Pack for mobile extensions provides support for the JSON data format, which is ideal for integration with mobile devices and RESTful JSON-based Web services. This makes it easy to connect a mobile device to a CICS service or to easily integrate it with a middle-tier mobile architecture, such as IBM Worklight Server. Best of all, the feature pack is freely available to download. Find out more at

How Hard Can It Be?
For many customers, their first foray into mobile with CICS is likely to be exposing existing CICS applications to mobile devices. Let’s examine the basic steps necessary to expose an existing CICS application as a JSON-callable service:

1. Identify the application to enable as a JSON-callable service.
2. Generate the bindings for each service operation you require (i.e., create, read, update, delete).
3. Define the required CICS PIPELINE resources to allow your service to be called.

Those of you familiar with CICS Web services might think those three steps sound similar to the process you follow today for Web service-enabling CICS applications, and you would be right. In its simplest form, we’re building a Web service that’s invoked using the JSON data format rather than a SOAP XML message.

Step 1: Breaking It Down
This first step is heavily dependent on the nature of your application, but is perhaps the most critical step because, at this point, you decide where within your application infrastructure you define the entry point for mobile workloads. 

This might sound obvious, but for applications that have a significant heritage, there’s a good chance they weren’t built with mobile devices in mind, and the degree of abstraction between the presentation layer, business logic and data might not be ideally suited to mobile integration. 

The key thing to consider is the interaction pattern that you’re building between the mobile device and the CICS service. An existing application that has been Web service-enabled might well have a significantly richer interface than is strictly necessary for a mobile solution.

Mobile developers, who perhaps haven’t participated in the service-oriented architecture (SOA) transformation of enterprise services, won’t necessarily appreciate that SOAP Web services are a different paradigm to the RESTful service approach that’s more prevalent among mobile development teams. In a RESTful architecture, the create, read, update and delete operations are discrete interfaces, whereas a traditional Web service commonly has a single, richer interface and the operation is defined as part of the payload.

On a mobile device the workflow tends to be more restrictive with fewer options, in part due to the restricted nature of the screen, so the interaction between the mobile device and the back-end service might also be better as a discrete operation. 

Mobile devices often operate with restricted bandwidth, potentially costing the end user, so restricting the data that’s sent between the mobile and the mainframe to the minimum required makes more sense. 

So, you have a choice: preserve the rich interface and reuse it on the mobile, which for many will be the shortest route to mobile enablement, or create a set of discrete interfaces for the mobile application.

Step 2: Show Me the Copybook
We imagine for many people the first time they approach CICS from a mobile device they will want to exploit an existing service probably written in COBOL. We’re going to assume that’s the case for the remainder of this article, and describe how to call a COBOL-based service from a mobile client.

Having decided on our target application interface, we now need to create the necessary bindings to convert the inbound JSON data into a COBOL language structure. The CICS TS Feature Pack for Mobile Extensions provides tooling in the form of an assistant, DFHLS2JS, a JCL procedure that takes as input a language structure, such as a COBOL copybook, and creates the required JSON schemas and bindings to map between the two.

Running the assistant is a simple process: You configure a few parameters that point to the source copybook, the language type you’re converting to/from, which in our case is COBOL, and indicate where you want the resulting binding file and request/response schemas to be created. This process is similar to creating a SOAP-based Web service.

Step 3: Defining the Required CICS Resources
Once you’ve created the binding files and schemas in the previous step, you need to add some resource definitions to CICS that define your newly created service(s). Again, this step follows the same pattern you would use for defining a normal Web service to CICS:

1. Define, install and enable a JVMSERVER. JSON parsing is dependent on the AXIS 2 run-time hosted in a JVMSERVER, which is eligible for offload to an IBM System z Application Assist Processor (zAAP).
2. Create a TCPIPSERVICE resource that defines the port on which inbound requests are received.
3. Create a pipeline configuration file. The feature pack contains a simple pipeline configuration file (jsonjavaprovider.xml) that you can use and customize (see Figure 1).
4. Create a PIPELINE resource that specifies the location of the pipeline configuration file and where the bind file for the service can be found in IBM zFS.
5. Perform a PIPELINE scan to automatically create the required WEBSERVICE and URIMAP resources necessary to invoke the service.

Assuming you have program autoinstall enabled, that’s it. If not, then you will also need to create program definitions for the programs defined to run in the pipeline.

Example PIPELINE Configuration File
We’ve highlighted the interesting parts of an example PIPELINE configuration file in Figure 1, showing that you must specify the JVMSERVER defined in step 1 and reference the AXIS 2 handler.


Mobilize Your Assets
Having come this far, you will be anxious to connect your mobile device to your new JSON service. If your company is serious about mobile (and whose isn’t?), then you will want to implement a suitable architecture to support your mobile projects. 

IBM Worklight is a mobile application platform that supports multiple mobile operating environments with the simplicity of a single codebase. In addition, IBM Worklight Server offers a middle-tier gateway that lets you easily integrate multiple back-end services from across your enterprise. The combination of IBM Worklight and CICS TS allows you to deploy powerful mobile solutions that exploit the value of your existing enterprise services hosted in CICS.

Mobile to Worklight to CICS
Figure 2 shows the basic flow of a request from a mobile device to IBM Worklight Server and from Worklight Server to CICS. At the bottom left of the diagram, you can see the CICS service. The first three steps outlined previously create all the necessary components to define this callable service. Now we’ll focus on the adapter code that resides in Worklight Server.


Worklight Server uses an adapter concept to interact with back-end services. The client code running on the mobile device makes a call to a procedure defined within an adapter. Procedures are written in JavaScript, making the development of adapter code simple and efficient. Worklight Server provides a set of predefined adapters that support SQL, Cast Iron, Java Message Service (JMS) and HTTP for SOAP and RESTful Web service requests.

Worklight adapters have three basic components:

• An XML file that describes the procedures you want to expose to the client application and its connectivity options. In addition, you can define a custom security test for each procedure.
• A JavaScript file that contains the implementation of your procedure
• Optionally, one or more Extensible Stylesheet Language (XSL) files that can be used to perform transformations on the data returned from the back-end service.

When a client application makes a call to a procedure, the Worklight Server checks if the procedure has been defined with a security test. If it has, and this is the first time the client has been authenticated, the server will invoke the test prior to driving the procedure. If the client has been authenticated on a previous request, then Worklight automatically grants access to the protected procedure. This is a simple, yet powerful, mechanism for authenticating a client prior to it making calls against the back-end server. If your organization uses LDAP to authenticate users, then you can take advantage of the LDAP authentication components supplied with Worklight.

To demonstrate just how easy it is to make a JSON request against a CICS service written in COBOL, lets consider the simple COBOL copybook example in Figure 3. Assuming we’ve performed the three basic steps described earlier to create the required binding files and CICS resources, all we need to know is how to code the request from the adapter that will call the CICS service. We aren’t going to worry about the call from the client into the adapter, although if you want to see how equally easy that is, there’s a list of resources at the end of this article that will take you to the online tutorials for Worklight.

Figure 4 shows our sample adapter code to make a request against our COBOL service. As we mentioned earlier, our adapter code is written in JavaScript, in the form of a JavaScript function. We pass a string into the function that will be passed through to our COBOL application—we aren’t including any validation here; we just want to show the basic steps for making a request.



Within our function, we create an object called jsonInputMessage. The first three elements define the type of request we’re making and include the uniform resource identifier (URI) we want to make the request against. This corresponds to the URIMAP resource we created when we performed step 3 earlier, and is defined at the time we run DFHLS2JS as part of step 2.

The final part of our jsonInputMessage are the parameters we want to pass to our COBOL service. You will notice that we’ve defined only the first of the two fields that appear in the COBOL copybook. This is possible because the PIPELINE inserts blanks for character fields that aren’t supplied as input; other fields, such as numerics, require you to supply a default value to prevent a conversion error from occurring.

The final line of code causes the Worklight server to invoke our CICS COBOL service, passing in the jsonInputMessage we’ve constructed. This sends the JSON message to CICS where the PIPELINE processes the input data and invokes the COBOL service, passing in the appropriately formatted data to match the copybook we supplied. The result from the CICS application is returned to the Worklight Server in JSON format, which sends the result back to the client application. It really is that simple! If you want to try it for yourself, you can download the Genapp support pack, which has a more complete sample based on an insurance application. In the resource list at the end of this article, you will find a link to a YouTube video of the insurance demo.

Other Things You Can Do With the Feature Pack
In addition to the DFHLS2JS assistant described earlier, a second assistant, DFHJS2LS, allows you to create the language structure from an existing JSON schema. This lets you expose CICS services using a RESTful architectural pattern, or to use an existing JSON format as an interface to CICS applications.

The feature pack also provides a linkable interface, DFHJSON, that lets you transform data from a binary format into JSON, and vice versa. This enables existing applications to start utilizing JSON-based data, converting it into structured binary data, or to create a JSON message from structured data that could be used to call an existing JSON service hosted elsewhere within your organization. To use this feature you need to have an AXIS 2 JVM server running.

The CICS TS Feature Pack for Mobile Extensions V1.0 brings JSON and RESTful capabilities to CICS, building on the powerful Web service technology CICS offers. As we’ve shown, it’s an easy process that will immediately be familiar to those who have used CICS Web services in the past, and for those who are new, it really is simple to get started. 

The feature pack is more than just a mobile enabler, as it offers you a simple, yet powerful, callable interface for transforming language structures into JSON and vice versa, further extending the options available for enhancing your existing enterprise applications.

• This article on IBM developerWorks describes the basic process for connecting a Worklight application to a JSON service, which could be CICS:
• The Worklight online documentation has a wealth of useful tutorials and details and is available at
• CICS Mobile video: