To follow the setup in this article you should already have performed the following: 

  • Setup CICS to access MQ, this includes adding the correct datasets to the CICS region STEPLIB, and defining the MQCONN resource definition.
  • Installed the CICS Explorer V5.2 and added the WDT tools if developing Web applications.
  • Successfully created and started a JVM server in CICS

You will require the following minimum software requirements:

  • CICS TS for z/OS V4.2 or later
  • An IBM Java SDK for z/OS supported by CICS TS
  • A Windows or Linux client with the CICS Explorer installed, using a supported IBM Java SDK.

The software levels used in this article are as follows:

  • IBM WebSphere MQ for z/OS V7.1.0.4
  • IBM CICS Transaction Server for z/OS V5.2
  • Windows 7
  • IBM CICS Explorer V5.2


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
  2. Configure the Eclipse IDE
  3. Setup 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 in the following directory

  • C:\Program Files (x86)\IBM\WebSphere MQ\java\lib

and the MQ OSGi bundle  in the following directory, where n is the maintenance level of MQ V7.1

  • C:\Program Files (x86)\IBM\WebSphere MQ\java\lib\OSGi

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 (, 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 at least 2 distinct types of Eclipse project you may be developing for use in CICS, either OSGi plugin projects if you are deploying into an OSGi JVM server, or web projects, if you are deploying web applications into a Liberty JVM server. The MQ Java classes are only supported in the OSGi JVM server environment.

The way you setup the Eclipse environment for a plug-in project 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 an Eclipse project in your workspace that exports the packages, or add the MQ supplied OSGi bundles to the Eclipse 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:

  1. Click on Windows – > Preferences -> Target Platform
  2. Click the Add button, and then click on Template, and select the CICS TS V5.2 item from the drop down list.
  3. Click Next and in the Target Content window click on Add -> Directory and then browse to the directory where the MQ OSGi bundle JAR is located.
  4. Click Next and the bundle will be displayed
  5. Click Finish, then Finish again, and then OK.

The workspace will now be updated to allow the both the MQ Java APIs and the JCICS APIs to be imported by a Java application.

3. Set up the CICS JVM server

Next we need to setup the JVM server environment.

3.1 Adding the native libraries

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:

  • /mqm/V7R1M0/java/lib

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.

  • LIBPATH_SUFFIX=/mqm/V7R1M0/java/lib

3.2 Adding the Java library to the OSGi framework

Next it is necessary to add the MQ Java libraries to the OSGi framework. These MQ OSGi bundles can be found in the same location as a native libraries.

Add the to the OSGi JVM server middleware bundles list using the OSGI_BUNDLES JVM server variable as follows:


Lastly restart your JVM server and deploy your Java application using a CICS bundle project.


Note: If using IBM MQ v8 for z/OS or later then when deploying the MQ OSGi bundles you should use the new composite bundles, and Using these bundles removes the restriction of not being able to run both IBM MQ classes for JMS and the IBM MQ classes for Java within the same OSGi framework. For further details refer to the IBM MQ V8 for z/OS Knowledge Center

Join The Discussion

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.