The MQ Service Provider for z/OS Connect
MattLeming 120000MN5R Visits (3384)
My colleague Mark wrote a blog last month on the new administrative REST API that was introduced in MQ 9.0.1. As the name suggests, that REST API is for administering queue managers, not for sending and receiving MQ messages.
But what if you do want to send and receive MQ messages using REST, what options are available to you? The standard answer used to be the IBM
What is z/OS Connect?
z/OS Connect is an IBM product that allows existing mainframe based assets to be exposed as RESTful APIS and services, without making any changes to those assets.
For example: you might have a CICS transaction that is used to check stock levels. Requests to the transaction are sent as a COBOL copybook describing which items are to be checked. Responses, indicating the number of items, are also returned in copybook form.
This transaction can very easily be run when on the mainframe, but what happens if there is a need to expose the same capability to applications that run in mobile or cloud environment? Applications in these environments normally interact with services using REST, and exchange data in JSON format, they don’t understand COBOL copybooks.
This is where z/OS Connect comes to the rescue! You can define a RESTful API in z/OS Connect which exposes your existing transaction in a way that is intuitive to cloud or mobile apps. At the same time you can define data transformations which will convert between the JSON payloads being sent over REST and the COBOL copybooks that the transaction uses.
This means that there is no change to the existing CICS transaction, it can be called by existing applications as normal. But it can also be called by new cloud and mobile based applications just like any other RESTful API.
There are two versions of z/OS Connect:
Why is this useful with MQ?
MQ is a very common way for different applications to communicate with each other. This is especially true on z/OS where there is tight integration between MQ and other subsystems via the CICS or IMS bridges, and the CICS or IMS adapters.
Continuing our stock check example, the CICS transaction that provides the stock check function might require that all stock check requests come in the form of an MQ message sent to a queue called StockCheckReq. The CICS transaction uses the CICS-MQ adapter to connect to the StockCheckReq queue and get messages. Each message is processed in turn and the result sent to the StockCheckRes queue. This transaction can easily be driven by any application that can access these queues using one of MQ’s programming APIs, for example a COBOL batch job using the MQI.
This is shown in the diagram below.
The approach described above works very well for applications that have easy access to the LPAR and can easily use one of MQ’s APIs. But what if you wanted to access the stock check transaction from a mobile app?
There are many ways in which this problem could be solved, but ideally the solution would meet these criteria:
This is where z/OS Connect comes in. MQ 9.0.1 ships with a z/OS Connect Service Provider, the MQ Service Provider for z/OS Connect - MQ Service Provider for short. This is a small piece of Java code which can be installed into z/OS Connect and provides the ability to talk to a particular z/OS asset, in this case an MQ queue manager.
Once z/OS Connect, and the MQ Service Provider, is installed the mobile app can send a JSON/REST request to z/OS Connect when it wants to invoke the stock check transaction. z/OS Connect will convert the JSON request into a COBOL copybook and pass it to the MQ Service Provider which will put the data into a message and send it to the StockCheckReq queue. This is processed as normal by the CICS transaction and the response sent to the StockCheckRes queue. The MQ Service Provider will pick up the response message and pass the message payload to z/OS Connect which will convert it from COBOL copybook format to JSON and send it back as the response to the original HTTP request. This is shown in the diagram below.
The mobile application doesn’t need to be aware of MQ at all. All it needs is the URL it has to send the request to and the expected format of the JSON request and response. Just like for any other REST API. Other than the installation of z/OS Connect and the MQ Service Provider, plus a bit of configuration of the MQ Service Provider, nothing needs to change at all on the z/OS LPAR. In particular existing batch jobs that also use the transaction don't need to change.
The MQ Service Provider
As mentioned above MQ’s support for z/OS Connect is in the form of the MQ S
The MQ Service Provider supports two types of service:
The MQ Service Provider aims to hide MQ from the applications that invoke it via REST. Therefore all of its behaviour, such as message expiry time, how long to wait when getting a message, etc. is configured in z/OS Connect using xml. Most applications will just use the defaults configured in xml and only send/receive message data in the form of JSON. More advanced applications might need to override the defaults using HTTP headers.
Both versions of z/OS Connect mentioned above are supported with the MQ Service Provider. The function provided by MQ stays the same regardless of version, but with z/OS Connect Enterprise Edition there are a number of additional capabilities that can be used with MQ such as the API Editor.
The MQ Service Provider is supported with MQ for z/OS version 8 and later. It can be obtained from either a MQ 9.0.1 installation or from FixCentral.
Where do I find out more?
There is now a video showing how to setup a one-way service here.
More information on the MQ Service Provider is available in the MQ KnowledgeCentre.
If you have questions then you can also add a comment to this blog or email me at lemi