Setting up your development environment

You can use the JCICS or JCICSX API to develop Java™ applications that can access CICS® resources. Both APIs are available in the IBM® CICS SDK for Java, Maven Central, or in the USSHOME directory of your CICS installation.

About this task

Both JCICS and JCICSX APIs provide you with the Java interface to access CICS services. The JCICS API is the Java equivalent of the EXEC CICS API that is provided for other CICS supported languages, such as COBOL. The JCICSX API supports a subset of JCICS functionality with new Java API classes that provide developers with the capabilities of mocking and remote development. The JCICSX API classes can be used together with the JCICS API, but only the commands using JCICSX can benefit from these enhanced features. See Java development using JCICSX for more information.

The table shows where the APIs are provided and what tools you can use to consume them.

Table 1. JCICS and JCICSX API locations
Java code authoring tool	JCICS API	JCICSX API classes
CICS Explorer®	Yes, provided in the preinstalled IBM CICS SDK for Java, which resolves dependencies automatically.	Yes, provided in the preinstalled IBM CICS SDK for Java in IBM CICS Explorer for Aqua 3.2¹ (Fix Pack 5.5.0.9) or later, which resolves dependencies automatically.
Apache Maven and Gradle (to access artifacts from Maven Central)	Yes. You can declare the dependency using any Java IDE that supports Gradle or Maven.	Yes. You can declare the dependency using any Java IDE that supports Gradle or Maven.
Any other tool, to import the API jars provided in USSHOME	Yes. You need to manually import the dependency.	Yes. You need to manually import the dependency.

Note: If you want to develop Java EE applications for CICS, you must install the IBM CICS SDK for Enterprise Java (Liberty) in CICS Explorer.

CICS Explorer provides the following tools for you to develop, package, and deploy Java applications that are hosted in the CICS JVM server:

The IBM CICS SDK for Java provides support for the JCICS API and JCICSX API classes.
Eclipse and the Eclipse Web Tools Platform provide the tools to develop Java EE applications.
The IBM CICS SDK for Enterprise Java (Liberty) provides the Java EE, Jakarta EE, MicroProfile and Liberty APIs in the form of a Java build path library or OSGi target platform.
CICS Explorer provides the tools to package, deploy, and manage Java applications within CICS bundles.
Explorer for z/OS provides the tools to work with files, data sets, and jobs on z/OS, including viewing JVM server log files.

The SDKs can resolve dependencies automatically as long as you add the correct library to your build path or select the correct OSGi target platform.

Consuming dependencies from Maven Central offers more flexibility in the choice of IDE and integrates easily into popular build toolchains such as Gradle or Maven. The Maven Central artifacts contain the JCICS, JCICSX, CICS annotation, CICS annotation processor libraries and a bill of material (BOM) for you to declare dependencies and develop applications for CICS in your IDE of choice. The artifacts can be obtained directly from Maven Central, or from locally hosted and allow-listed repositories using tools such as JFrog Artifactory or Sonatype Nexus. You can then use the CICS-provided Maven and Gradle plug-ins to package and deploy CICS bundles that contain your applications into a CICS region.

Procedure

To use the SDKs in CICS Explorer:
1. The IBM CICS SDK for Java is preinstalled in CICS Explorer. If you want to develop Java EE applications, install the IBM CICS SDK for Enterprise Java (Liberty) into your CICS Explorer as a plug-in. For instructions, see Downloading and starting CICS Explorer in the CICS Explorer product documentation and Installing the CICS SDK for Java EE, Jakarta EE and Liberty in the CICS Explorer product documentation.
2. Restart your development environment.
3. Add libraries to your build path or select your target platform, for the SDK to revolve dependencies correctly for your projects. See Step 1 in Creating a Dynamic Web Project, Creating an OSGi Application Project, and Creating an Enterprise Application Project.
To use Gradle or Maven:
1. Ensure your environment fulfills either of the following prerequisites:
  - If you want to use Gradle or Maven with the command line, you must install them on your machine. See Downloading and Installing Maven and Installing Gradle.
  - Your IDE must support Gradle or Maven. Such IDEs include Eclipse, IntelliJ IDEA, and Visual Studio Code.
2. Create your project using Gradle or Maven and import dependencies based on the API you want to use, as described in Managing Java dependencies using Gradle or Maven. You might need to add extra Gradle or Maven configuration, depending on your project type. See Step 1 in Creating a Dynamic Web Project, Creating an OSGi Application Project, and Creating an Enterprise Application Project.
To use the JAR files in the USSHOME directory, see Manually importing Java libraries.

Results

Your development environment is ready to develop Java applications for CICS.

What to do next

For JCICS users, you can refer to the JCICS Javadoc information. If you're using the IBM CICS SDK for Java, you can use the examples that are provided with the IBM CICS SDK for Java to get started. For more information, see Java samples: Servlet examples.

For JCICSX users, see JCICSX Javadoc for more information.

¹ Aqua refers to IBM Explorer for z/OS® Aqua.