Upgrading the Java environment

If you run Java™ applications in CICS®, whether OSGi, Axis2, or Liberty, you have some changes to make when you upgrade your version of CICS. This information applies to all currently supported CICS TS releases, regardless of your current release and the target release.

Before you start upgrading the Java environment, first upgrade the CICS regions, as described in Upgrading CICS regions.

If you are upgrading from an end-of-service release, you might need to take additional actions that are relevant to your current, end-of-service release. You can find additional upgrade actions for migrating from end-of-service releases in Upgrading from end-of-service releases.

Upgrade actions

Table 1 lists the actions you must perform when upgrading to a higher CICS release, regardless of your current release and the target release. The sections that describe these actions in detail are tagged with All versions.

Table 1. Common actions
Action Mandatory or optional?
Java 21Check your programs do not assume that the default encoding is EBCDIC Optional, but recommended
Check your programs for deprecated APIs Optional, but recommended
Review your JVM profiles for new settings Mandatory
6.3 Migrate to Java version 17 or later Mandatory

Check your programs do not assume that the default encoding is EBCDIC

All versions

Java 21 Applies to Java 21.

In Java 21, the default character set for standard Java APIs is UTF-8, except for the console input and output encoding. For more information, see Migrating applications to new Java versions.

Check your programs for deprecated APIs

All versions

To avoid potential problems with deprecated APIs, develop all new Java programs for the latest release of CICS using an application development environment that supports the same version of Java as the environment used by CICS. If the older environment does not use APIs that are removed in the newer version of Java or CICS, you can still run code that was compiled with an older version of Java in the new runtime environment. For details, refer to the Target Platform setting when you use the IBM® CICS SDK for Java.

Review your JVM profiles for new settings

All versions

Settings in JVM profiles change from release-to-release so you must upgrade all your JVM profiles. A good practice is to use the sample JVM profiles that come with the latest release, and reapply any customization that you made to those JVM profiles in previous releases.

For more information about the sample profiles, see JVM profile validation and properties. For a summary of the changes to the JVM profiles, see Changes to JVM profiles.

Migrate to Java version 17 or later

6.3

CICS TS 6.3 supports Java version 17 and later. Support for Java version 8 and version 11 is removed.

Update the JAVA_HOME option in your JVM profile to the location of your installed IBM Semeru Runtime® Certified Edition for z/OS® Version 17 or Version 21. For more information, see Setting the version of the Java runtime

Java aims to be compatible with the previous versions of Java. Existing applications that were compiled with a previous version of Java should work, unchanged, in the Java 17, or later, runtime environment.

Java applications that manipulate the Java bytecode must be updated to tolerate the Java 17, or later, bytecode, if they do not already. An IllegalArgumentException is thrown when the Java application does not tolerate the Java bytecode of the current version of Java. For example,
java.lang.IllegalArgumentException: Unsupported class file major version 61

Spring Boot applications compiled with Java 8 compiler use bytecode manipulation libraries that do not tolerate the Java 17, or later, bytecode, and can fail in CICS. Recompile these applications with a Java 17, or later, compiler and updated dependencies.