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.
Before you start upgrading the Java environment, first upgrade the CICS regions, as described in Upgrading CICS regions.
Upgrade actions
| Your current version | Action | Mandatory or optional? |
|---|---|---|
| |
Upgrade the IBM SDK for z/OS | Mandatory |
| Check your programs for deprecated APIs | Optional, but recommended | |
| Review your JVM profiles for new settings | Mandatory | |
| |
If you have not already migrated to OSGi, change your Java applications to run in a JVM server | Mandatory, if you haven't already migrated to OSGi |
| |
Check whether applications that run in a JVM server depend on IBM or vendor classes in the supplied JRE | Mandatory, if you haven't already migrated to OSGi |
| |
Check that MEMLIMIT allows sufficient storage for 64-bit JVMs | Mandatory, if you haven't already migrated to OSGi |
| |
Change applications that use EJBs or stateless CORBA objects | Mandatory |
| If you use the CICS Liberty security feature, check for restrictions | Mandatory | |
| Import classes from JCICS API or IByteBuffer | Mandatory | |
| |
If you use the CICS Liberty security feature and do not use autoconfigure, define your own SAF registry. | Mandatory |
Upgrade the IBM SDK for z/OS
CICS runs Java applications that use the IBM® 64-bit SDK for z/OS®, Java Technology Edition, Version 7, Version 7 Release 1 or Version 8. CICS supports only the 64-bit version of the SDK and not the 31-bit version. If you are using an earlier version, such as Java Version 1.4.2, Version 5, or Version 6, or any 31-bit version, you must replace this version with a supported version.
- Check that any Java programs that use the Java Native Interface (JNI), including vendor products, can run with the 64-bit version of the SDK.
- Ensure that your applications are threadsafe, and repackage your JARs as OSGi bundles. Deploy the OSGi bundles within a CICS bundle to zFS, making sure that you specify the correct target JVMSERVER resource. For more information see JVM server runtime environment.
Check your programs for deprecated APIs
Java Standard Editions Products on z/OS gives details about any compatibility issues between the Java APIs, and compatibility issues that are specific to the IBM SDK for z/OS. Check your Java programs for compatibility issues between the supported IBM SDK for z/OS and previous versions. Make any changes that are required to enable your programs to run with the supported versions.
- In Version 5.3, JCICS class library methods Program.xctl(), xctl(byte[] CA) and xctl(Channel chan) are removed. A Java developer switching their target platform to Version 5.3 will see an Eclipse error saying the methods do not exist, and the application will not compile. An application compiled against a target platform for a previous version of CICS will result in a Java runtime exception.
- In Version 5.2, JCICS class library methods Program.xctl(), xctl(byte[] CA), and xctl(Channel chan) are depreciated. A Java developer switching their target platform to Version 5.2 will see an Eclipse warning marker saying the method is depreciated. The application will successfully compile and run.
- In Version 5.1, the CCI Connector for CICS is obsolete and is no longer available. If you have any Java applications that use this deprecated interface, you must change the application. You can use the JCICS Link() method in the Program class instead.
- In Version 5.1, CICS applications that run in an OSGi framework can use the JCICS API to create threads that start CICS tasks on T8 TCBs. These tasks can use JCICS to access CICS services. The CICSExecutorService class in JCICS provides an implementation of the Java ExecutorService interface. Use this class instead of the Thread.start() method.
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 CICS Explorer® SDK.
Review your JVM profiles for new settings
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.
If you have not already migrated to OSGi, change your Java applications to run in a JVM server
Because pooled JVMs are not supported, you must migrate your existing Java applications to run in a JVM server. The JVM server is a multithreaded environment that uses an OSGi framework, so you must ensure that your applications are threadsafe and comply with the OSGi specification. You can use the CICS Explorer® SDK to repackage the applications as OSGi bundles and deploy them to run in a JVM server.
- Check that the Java application is threadsafe. The IBM website developerWorks® has useful information about Java: http://www.ibm.com/developerworks/java/ .
- Check that the Java application does not use the System.exit() Java method. If this method is used, both the JVM server and CICS shut down.
- Package the Java application
as one or more OSGi bundles by either conversion, injection or wrapping,
ready for running in the JVM server environment.
- Conversion
- If you already have an Eclipse Java project for the Java application, you can convert the project to an OSGi plug-in project. This method is the preferred best practice.
- Injection
- Create an OSGi plug-in project and import the contents of the existing JAR file. This method is useful when the application is already threadsafe and no refactoring or recompiling is required.
- Wrapping
- Create an OSGi plug-in project and import an existing binary JAR file. This method is useful in situations where there are licensing restrictions or where the binary file cannot be extracted.
- Add the CICS-MainClass declaration to the project manifest. Right-click
the project name and select .
The following example is the manifest file from the CICS Hello Examples project. The sample contains two classes, HelloCICSWorld and HelloWorld , which are both declared in the manifest file in the CICS-MainClass declaration. You must add a CICS-MainClass declaration for each class that is used in your application.

- Deploy the OSGi bundle in a CICS bundle to the zFS file system. Specify the target JVMSERVER resource in the plug-in resource file of the CICS bundle.
Check whether applications that run in a JVM server depend on IBM or vendor classes in the supplied JRE
If you are running Java applications in a JVM server, check whether the applications use IBM or vendor classes that are available in the JRE. The OSGi framework has stricter rules for loading classes from the JRE, and you might need to change your applications to run them in a JVM server in this release.
You do not need to do this for the CICS Java classes, as the JCICS classes are automatically made available in the OSGi framework.
Any package that is prefixed with java is loaded by the OSGi framework as required by the application. If an application uses an IBM or vendor package that is supplied with the JRE, such as org.xml.sax , you can follow the procedure outlined below to make these classes available. If you do not change the application, transactions abend with an AJ05 code and java.lang.ClassNotFoundException errors are written to the JVM server error log and CICS system log.
- Change the application to add an import for the exported package in the appropriate OSGi bundle manifest. Each OSGi bundle that requires a class from an IBM or vendor package must declare the package in the manifest.
- If you still receive the java.lang.ClassNotFoundException exception for the
vendor or JRE package, then you must extend the JVM property
org.osgi.framework.system.packages.extra to contain your required package, for
example:
-Dorg.osgi.framework.system.packages.extra=org.xml.sax,org.xml.sax.helpers - Restart the JVM server to pick up the properties change.
- Deploy the updated application bundle to CICS.
From v5.3 the preferred way to declare your applications use of JRE packages is to use the system packages extra property with an explicit Import statement in the manifest of the application, in favor of adding packages to bootdelegation.
- org.ietf.jgss
- org.omg.*
- org.w3c.*
- org.xml.*
Check that MEMLIMIT allows sufficient storage for 64-bit JVMs
Set the value for the z/OS MEMLIMIT parameter equal to or greater than 6 GB. The default value in z/OS for MEMLIMIT is 2 GB.
CICS requires a MEMLIMIT value of 10 GB; any additional use by applications or JVMs should be allowed for with a larger value of MEMLIMIT. If you attempt to start a CICS region with a MEMLIMIT value that is less than 10 GB, message DFHSM0602 is issued, a system dump with the dump code KERNDUMP is produced, and CICS terminates.
You cannot alter the MEMLIMIT value for the CICS region while CICS is running. You can specify a new MEMLIMIT value on the next start of the CICS region.
Change applications that use EJBs or stateless CORBA objects
CICS support for enterprise beans (Enterprise JavaBeans, or EJBs) and CICS support for the CORBA architecture (using stateless CORBA objects) are no longer provided in CICS Transaction Server. If you are running enterprise beans or stateless CORBA object applications in CICS in the pooled JVM environment, you must migrate your applications to run in the JVM server environment, and you must use standard functions of the IBM 64-bit SDK for z/OS, Java Technology Edition for intercommunication between components.
If you use the CICS Liberty security feature, check for restrictions
- The Liberty Angel process must be started.
- Only one Liberty JVM server can be run per region with the CICS Liberty security feature enabled.
Import classes from JCICS API or IByteBuffer
| File name | OSGi bundle symbolic name | Description |
|---|---|---|
| com.ibm.cics.samples.jar | com.ibm.cics.samples | Samples for redirecting System.out and System.err. Replaces the dfjoutput.jar file. |
| com.ibm.cics.server.jar | com.ibm.cics.server | The JCICS API. Replaces the dfjcics.jar file. |
| com.ibm.record.jar | com.ibm.record | The Java API for legacy programs that use IByteBuffer from the Java Record Framework that came with VisualAge®. Previously in the dfjcics.jar file. |
If you use the CICS Liberty security feature and do not use autoconfigure, define your own SAF registry.
<safRegistry id="saf"/>
If you
are using autoconfigure, this is defined for you.