This article will help you to get started with the IBM CICS remote development feature for Java. The feature allows you to locally test and debug Java EE applications that use the Java EE Connector Architecture (JCA) to make External Call Interface (ECI) requests to link to CICS programs.


You will install the feature into your local Liberty server, and update server.xml with connection information. When your applications run in the local Liberty server ECI requests are sent remotely to CICS. This makes the whole development experience easier and quicker, since application do not need to be deployed to CICS for unit testing. Once the application is ready, it can be packaged and deployed without change into a CICS Liberty server for integration testing.

Note: this feature does not support local test and debug of Java CICS APIs (JCICS). If you are only using JCICS to link to a CICS program, you can switch to JCA to keep your application portable and use this feature for remote test and debug.

Setting up your development environment

To get started, if you don’t already have the IBM CICS Explorer, install it by following the Download Eclipse Tools instructions. The CICS Explorer is not essential to using the feature, but is useful to work with CICS resources and to create a CICS bundle to package the Java application for deployment into a CICS Liberty server.

Once you have a CICS Explorer installation, you need to install the IBM CICS SDK for Servlet and JSP support feature, as follows:

  1. Select Help > Install New Software…
  2. In the Work with… drop down box you should see IBM Explorer for z/OS Update site as an option. If not click Add… and add an update site with the name IBM Explorer for z/OS Update site and the following URL :
    http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/
  3. Select to work with this update site and in the feature list select IBM CICS SDK for Servlet and JSP support then follow the wizard to install the feature.
  4. At the end of the installation you will need to restart CICS Explorer.

You now have everything you need to get started with developing for Liberty in CICS.

Setting up a local Liberty server

Now we have a development environment installed, we need to configure all the necessary resources. This includes a Liberty server and the required features.

  1. Start by opening the Servers view in Explorer. You can do this by clicking Window > Show View > Other… and searching for Servers. Once you have opened the view, right click anywhere in the view and select New > Server, or click on the hyperlink as shown below.
    Eclipse Server view
    The following dialog will appear:
    02.NewServers
  2. Select WebSphere Application Server Liberty as the server type and leave the other options as the defaults. When ready click Next >
  3. You can keep most of the options on the following page the same, just select Install from an archive or a repository to download the runtime environment.
    03.NewServers
  4. On the next page you enter a destination path for your new server on your workstation, for example /home/mark/liberty8559
    04.NewServers
  5. Select the option to Download and install a new runtime environment from ibm.com and select whichever option suites your requirements, for example WAS Liberty 8.5.5.9 Runtime, then select Next >
  6. Note: support for Liberty features within CICS, and the underlying Java EE version is dependent on CICS release and APARs applied, please check the CICS Knowledge Center for the features are supported in your release of CICS and keep this in mind when developing your application.

  7. On the next page of the wizard you can select any additional features that you want to install. To use the IBM CICS remote development feature for Java, type CICS into the filter text box and select Install next to the feature, as shown below:

    04a.NewServers

    All other additional features are optional and depend on what you want in your Liberty server. If you do not require any additional features, click Next through the wizard and finally click Finish.

    When you click Finish the Liberty runtime will be installed and you should see the following message:

    05.NewServers

We have now installed a local Liberty environment and the remote development feature and can use it in our configuration. Open up server.xml, as shown below:

06.ServerXML

In the source tab add the following element to the <featureManager> element:

<feature>usr:jcaRemoteEci-1.0</feature>

And add these additional elements:

<connectionFactory id="defaultCICSConnectionFactory"
	jndiName="eis/defaultCICSConnectionFactory">
	<properties.com.ibm.cics.wlp.jca.remote.eci
		serverName="tcp://hostname:port"/>
</connectionFactory>

The hostname and port need to be set to the hostname and port specified in an IPIC protocol TCPIPSERVICE in the target CICS region. For more information on how to setup this connection, including how to secure, trace, and other options visit the CICS remote development feature for Java topic in the CICS Knowledge Centre.

Application development

We will use a simple web application example to show how to deploy it into your local Liberty server. For a more detailed discussion on JCA and interacting with CICS see the article Porting JCA ECI applications into a CICS Liberty JVM server.

Our example uses JCA to interact with the GENAPP insurance application sample, and in particular the program to retrieve customer information.

To deploy our application, we can choose the option to run on our local server:

07.RunOnServer

When deployed you should see the following output in your Eclipse console stating that the application is now available.

08.ApplicationAvailable

Now that the application is available we can navigate to the web application, as shown below, and in our example can enter a customer number and click on search to retrieve customer information.

09.ApplicationRunning

This sends a request to a servlet that uses JCA to call a CICS program which returns customer data from DB2.

10.ApplicationResults

We’ll now show debugging in action.

We will set a break point just before we set the customer number in the COMMAREA object we send to our CICS program. This will allow us to step through our application from this point.

11.SetBreakpoint

Once we have set this breakpoint we now need to restart the Liberty server with debug enabled. To do this right-click on the local Liberty server and select the option to Restart in Debug.

12.RestartInDebug

This will restart the Liberty server with debug supported, allowing breakpoints to be used. Now, when we send in a new request, we hit the breakpoint and Eclipse automatically switches to the debug perspective.

13.DebugRequest

14.BreakpointHit

We can see the customer number which we set on our applications web page in the Variables view, and using this Variables view change the value of this variable, and continue stepping through the code using the standard eclipse process. This variable change is shown below:

15.VariablesOriginal

Here, we change the cusNum variable from 3 to 5.

16.VariablesChanged

After making this change the application we can now step through the code, as shown below, and when we hit the following line we call out of our local Liberty server to the program in CICS.

17.StepOver

18.LinkToCICS

Once we have finished debugging we can choose to Resume the application.

19.Resume

The application now parses the response and formats this data and passes back to the browser. We can see here even though we asked for customer 3, the code retrieved customer 5 because we changed it during the debug.

20.ApplicationResultsChanged

This article has highlighted some of the core capabilities of the IBM CICS remote development feature for Java, showing how you can test and debug and application within your development environment.

References and Resources

IBM CICS remote development feature for Java – Introduction video – ibm.biz/cicsremotejavaintro
IBM CICS remote development feature for Java – Demo video – ibm.biz/cicsremotejavademo
Download Eclipse Tools – https://developer.ibm.com/mainframe/products/downloads/
CICS remote development feature for Java Knowledge Centre topic – https://www.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.java.doc/topics/dfhpj2_jca_remote_eci.html
Porting JCA ECI applications into a CICS Liberty JVM server – https://developer.ibm.com/cics/2015/07/23/porting-jca-eci-applications-into-a-cics-liberty-jvm-server/

3 comments on"Getting started with the IBM CICS Remote Development Feature for Java"

  1. Thank you for the detail of how to set up the remote CICS JCA in Eclipse!!!

  2. Many thanks for your detailed blog on the dev setup with remote connectivity. In our project, we do not have access to client’s CICS environment at development stage. What are the options we have to setup our local environment without remote connectivity to the CICS region?

    • Mark Hollands August 17, 2016

      Hi, thank you for your question. Unfortunately, if you do not have access to CICS your options are limited, however there are solutions available that let you “mock” the responses that you would get when using JCA or JCICS. I would recommend the following blog as a good starting point for how you can use Mockito or PowerMock to mock responses, for example when unit testing applications.

      https://developer.ibm.com/cics/2014/10/31/unit-testing-jcics-applications/

Join The Discussion

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