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:
- Select Help > Install New Softwareâ€¦
- 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 :
- 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.
- 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.
- 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.
The following dialog will appear:
- Select WebSphere Application Server Liberty as the server type and leave the other options as the defaults. When ready click Next >
- 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.
- On the next page you enter a destination path for your new server on your workstation, for example /home/mark/liberty8559
- 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 220.127.116.11 Runtime, then select Next >
- 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:
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:
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.
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:
In the source tab add the following element to the
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.
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:
When deployed you should see the following output in your Eclipse console stating that the application is now available.
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.
This sends a request to a servlet that uses JCA to call a CICS program which returns customer data from DB2.
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.
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.
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.
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:
Here, we change the cusNum variable from 3 to 5.
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.
Once we have finished debugging we can choose to Resume the application.
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.
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/