Using the IBM MQ classes for Java with a CICS JVM server
Phil_Wakelin 20000028VV Comment (1) Visits (2445)
This article describes how to deploy a Java application that uses the IBM MQ classes for Java into a CICS OSGi or Liberty JVM server
To follow the setup in this article you should already have performed the following:
You will require the following minimum software requirements:
The software levels used in this article are as follows:
About this task
The MQ Java classes can be used in a CICS Java application to get and put messages to queues, using the MQ connection that is maintained by CICS. To develop the Java application you will first need download the MQ JAR files to your workstation, and then add these to your Eclipse development environment. Then having developed your application, you will need to add your application to a CICS bundle project, export to zFS, and install it into the JVM server. The CICS JVM server environment must then be configured with the correct levels of the MQ Java and native libraries, and these much match the level of MQ libraries specified in the CICS STEPLIB.
The following 3 steps will need to be performed to configure your Eclipse environment and the CICS JVM server:
1. Download the MQ JAR files
To develop your Java application you will require access to the MQ Java classes, unless you have the MQ product installed on your workstation, these should be obtained from the MQC71 SupportPac, which entitles you to download the MQ V7.1 clients free of charge.
Having download and installed the SupportPac you will find the MQ JAR file com.ibm.mq.jar in the following directory
and the MQ OSGi bundle com.
See the following topic in the MQ information center for further details on the MQ classes for Java.
2. Configure the Eclipse IDE
The development environment, for Java programs that are developed for CICS, is the Eclipse Integrated Development Environment (IDE). Eclipse is an open development platform, produced by the Eclipse Foundation (www.eclipse.org), composed of extensible frameworks, tools, and run times for building, deploying, and managing software across the lifecycle. In this section, we assume you have already setup this environment and provide instructions on installing both the MQ Java libraries into this environment. For further details on installing the CICS Explorer SDK for developing CICS Java applications refer to the IBM Redbook, CICS and the JVM server: Developing and Deploying Java Applications, SG24-8038
There are 2 distinct types of Eclipse project you may be developing for use in CICS, either OSGi plugin projects if you are deploying into a OSGi JVM server, or web projects, if you are deploying servlet or restful web applications using a Liberty JVM server. The way you setup the Eclipse enviroment for each of these types of applications is as follows:
2.1 OSGi plugin project
An OSGi plugin project is used to create an OSGi bundle for deployment to an OSGi JVM server. To make the MQ Java classes available to an OSGi plugin project, you can either create a wrapper OSGi project, or add the bundles to the Target Platform. The usual way is to use the Eclipse Target Platform as this is the most flexible method.
To do this perform the following steps in Eclipse:
The OSGi environment will now have been updated to include both the MQ OSGi bundle and the CICS OSGi bundle required for development.
2.2 Web applications
There are 2 distinct ways of developing a Web application to run in a Liberty JVM server. You can either use either an OSGi application project (or EBA) or a dynamic Web project (or WAR).
2.2.1 OSGi application project
An OSGi application project is a superset of OSGi projects, such as Web enabled OSGi bundles (WABs) and OSGi bundles or fragments. The OSGi application project is deployed as an EBA archive, which has the distinct advantage that all the code in the referenced projects are visible to the deployed Web application. This means that code can be packaged as OSGi bundles and reused or shared between different Web applications in the same EBA.
To make the MQ Java classes available to an OSGi application project, you should use the same method as for an OSGi plugin project, and add the MQ OSGi bundle to the Target Platform. However, you should use the CICS TS V5.2 with Liberty and PHP Target platform to ensure the web development libraries are also included in the Target Platform.
2.2.2 Dynamic web project
If using a dynamic Web project, this will create a WAR file archive for deployment. This doesn't use the OSGi framework in Eclipse and so simply requires that the MQ JAR files are added to the project build path.
To update the project build path do as follows:
The build path of the project should now have all the correct interfaces for development of a web application using both CICS and MQ APIs.
3. Set up the CICS JVM server
MQ on z/OS supplies the JARs and native libraries (DLLs) in the /usr/lpp zFS filing system, and both of these must be added to the JVM server enviroment to use the MQ Java classes. On our system they could be found in the following zFS directory:
The native libraries should be added to the JVM server library path, so add the lib directory to the LIBPATH_SUFFIX option of the JVM server as follows. You should ensure that the version of these libraries is the same as the MQ version specified in the CICS STEPLIB datasets.
Next it is necessary to add the JAR libraries to the classpath of the JVM server. These can be found in the same location as a native libraries. How you configure the classpath depends on what type of Java application archive you are deploying, there are 3 possibilities as follows:
3.1. If deploying an OSGi bundle to an OSGi JVM server
Add the com.
3.2. If deploying a WAR to a Liberty JVM server
Add the MQ JARs to the Liberty global library, which will add them to the classpath for all non-OSGi web applications (such as WARs). The global library is available to all non-OSGI applications installed in a Liberty JVM server, and can be defined in the Liberty server.xml configuration file as follows:
<fileset id="mqjars" dir=
Note these libraries can not be used by an Enterprise Bundle Archive (EBA) deployed into a Liberty JVM server, for further details refer to the WebSphere Application Server information center topic
3.3. If deploying an EBA to a Liberty JVM server
Add the com.
<fileset id="mqosgilib" dir=
Lastly restart your JVM server and deploy your Java application using a CICS bundle project.