Java development using JCICS

You can write Java™ applications to access CICS® services by using the Java APIs provided by CICS. The JCICS API supports most of the CICS functions provided by the EXEC CICS API.

Contents
Why use JCICS? Restrictions of JCICS JCICS usage and samples Troubleshooting

Why use JCICS?

Java is one of the most popular programming languages for modern application development. Compared to the EXEC CICS API, which is provided for other CICS supported languages such as COBOL, the JCICS API allows you to write applications in Java and call into CICS services directly. This makes it easier for Java developer to write CICS applications.
Unlike other CICS high level languages, no translation step is necessary during compilation as the underlying EXEC CICS calls are dynamically generated via the Java Native Interface (JNI).
The JCICS API supports most of the functions of the EXEC CICS API and is tightly coupled with it. Therefore, if you understand the EXEC CICS API and have some knowledge of Java, you can familiarize yourself with JCICS quickly.

Restrictions of JCICS

The following restrictions apply to Java applications written in JCICS:

The classes in JCICS cannot be run remotely in development environments. If you need to link to a remote CICS program from your workstation, consider using the JCICSX API classes.
It's not as easy to mock using the JCICS API as using JCICSX.
The syntax of JCICS resembles the EXEC CICS commands in design so might not be as natural as that of other Java APIs. As an alternative, you can use the JCICSX API classes, which take advantage of more recent Java constructors that might be more familiar to some Java programmers.
Do not use the System.exit() method. Using this method when the application is running in a JVM server will terminate the JVM server, quiesce CICS, and might lead to data inconsistency. You can use a Java security policy, code scans, or other measures to prevent the System.exit() method from being called.
Do not share JCICS objects between threads. You can only call instance methods on JCICS objects from the thread that created them.
Do not use finalizers in CICS Java programs.

If you are using JCICS in an OSGi environment, also see Guidance for using OSGi.

JCICS usage and samples

Resolving the JCICS dependency

You can get the JCICS API from any of the following places:

The build path library supplied with the IBM® CICS SDK for Java in CICS Explorer®.
When using CICS Explorer to add a library to your project, JCICS will automatically be available as an API in your client. See Step 1 in Creating a Dynamic Web Project to configure your Dynamic Web project to target CICS TS. If you haven't installed CICS Explorer, install it as described in Setting up your development environment.
The com.ibm.cics.server artifact on Maven Central. If you haven't installed Gradle or Maven, install either of them as described in Setting up your development environment.
If your enterprise uses locally hosted or allow-listed repositories, you can use tools such as JFrog Artifactory or Sonatype Nexus to configure the artifact to be obtained from such repositories.
The com.ibm.cics.server.jar file supplied with CICS in the USSHOME directory. For instructions, see Manually importing Java libraries.

Note: If you are importing the JCICS package into an OSGi bundle, you need to specify the package version. For more information, see Guidance for using OSGi.

Developing applications in JCICS

Use the classes from the JCICS library in the same way as Java classes. For explanation of each JCICS class, see JCICS Javadoc information. For examples and full sample code, see JCICS API services and examples and Sample CICS Java applications in GitHub.

When developing for CICS, mind that CICS attempts to pass control to the method with a signature of main(CommAreaHolder) in the class specified by the JVMCLASS attribute of the PROGRAM resource. If this method is not found, CICS tries to invoke method main(String[]).

Troubleshooting

You can use your Java IDE's debugger, console message, and error handling information to debug your applications. In addition, you can use the CEDX transaction to test your application program in CICS.

If an error that relates to CICS occurs, for example the remote JVM server or the CICS transaction, a response (RESP) code is returned. The system programmer can use the JVM server's traces and logs for debugging. For more information, see Troubleshooting Java applications.