Explore the Java APIs

CICS provides two versions of API to develop Java™ applications that can access CICS® resources: JCICS and JCICSX. JCICS is the Java equivalent of the EXEC CICS API that is provided for other CICS supported languages, such as COBOL. JCICSX allows remote execution in development environments but it does not cover as much of the EXEC CICS API as JCICS. It is valid to use both versions of API in the same application but you cannot use the remote execution capability of JCICSX if you have both JCICSX and JCICS calls in the same piece of code that you try to run remotely.

In many aspects, the two versions of the API are the same, but there are some significant differences.
Aspect Same for both APIs? Different between APIs?
Where the APIs are provided ✓  
What Java IDEs you can use ✓  
Compatibility ✓  
Specification ✓  
Why use one API over the other?   ✓
Restrictions   ✓
EXEC CICS API support   ✓

Where the APIs are provided

The locations are the same for both JCICS and JCICSX:
  • IBM® CICS SDK for Java
  • Maven Central
  • USSHOME directory of your CICS installation
Find out more:

What Java IDEs you can use

The tool choice is the same for both JCICS and JCICSX:
  • The IBM CICS SDK for Java that is preinstalled in CICS Explorer® and IBM Developer for z/OS, or can be installed as a plug-in into Eclipse.
  • Bring your own Java IDE to access the CICS-provided Gradle or Apache Maven artifacts or plug-ins.
Find out more:

Compatibility

JCICSX is available from CICS TS 5.6. The target CICS region needs to run a Liberty server that hosts the remote JCICS HTTP API. This API is not enabled by default; add cicsts:jcicsxServer-1.0 to server.xml to enable it.

Your ability to mix APIs is the same for both JCICS and JCICSX. The JCICS and JCICSX API classes can be used together but only the commands that use JCICSX can benefit from the enhanced features of JCICSX. You can write JCICSX code that looks almost identical to JCICS code, with some stylistic concessions to making it easier to mock.

Find out more:

Specification

Both APIs are specified in Javadoc.

Find out more:

Why use one API over the other?

JCICS supports most functions that are available in the EXEC CICS API. If you need this breadth of capability, choose JCICS.

JCICSX does not cover as much of the EXEC CICS API functions but it offers local debugging, hot-swapping, and therefore a much more natural development cycle:
  • The classes allow easy mocking and stubbing.
  • The classes can be run remotely in development environments. No modification is required to the application code whether it runs in CICS or on your local workstation.
  • The syntax is simpler and more natural and can result in a more fluent way of using the API.
Find out more:

Restrictions

JCICS has the following general restrictions:
  • The classes in JCICS cannot be run remotely in development environments.
  • Do not use the System.exit() method or finalizers.
  • You can call instance methods on JCICS objects only from the thread that created them.
JCICSX has the following general restrictions:
  • Supports only a subset of CICS functions that addresses the most common scenarios for Java in CICS
  • JCICSX API classes do not work correctly within worker threads that are dispatched as part of an asynchronous servlet.
  • Remote development is available only for applications that are themselves deployed to Liberty.
Find out more:

EXEC CICS API support

JCICS supports all EXEC CICS API commands except the following:
  • Unmapped APPC conversations
  • SEND MAP and RECEIVE MAP (BMS)
  • DUMP
  • Storage management that uses CICS services: for example, GETMAIN and GETMAIN64, FREEMAIN and FREEMAIN64
  • Spool commands: SPOOLOPEN, SPOOLWRITE, SPOOLREAD, SPOOLCLOSE
JCICSX supports only the following EXEC CICS API commands:
  • DELETE CHANNEL
  • GET CONTAINER
  • QUERY CHANNEL
  • ENDBROWSE CONTAINER
  • GETNEXT CONTAINER
  • PUT CONTAINER
  • STARTBROWSE CONTAINER
  • LINK PROGRAM
Find out more:

Where next?

Get started How it works: Java in CICS Design choices for Java in CICS
What you need to know about CICS This page Try Java in our sandbox
Try Java in your environment Get involved FAQ