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 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.

Download and install the IBM 64-bit SDK for z/OS, Java Technology Edition, Version 7, Version 7 Release 1 or Version 8 from Java Standard Editions Products on z/OS , then make the necessary changes in your CICS environment. If you encounter problems see Troubleshooting Java applications.
  1. 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.
  2. 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.

Back to top

All versions

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 addition, the following CICS JCICS APIs have been deprecated or removed:
  • 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.

Back to top

All versions

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.

Note: From CICS TS v5.3 the default location of output files is relative to the directory structure WORK_DIR/<applid>/<jvmserver> rather than WORK_DIR. The default output file names, previously prefixed with <applid>.<jvmserver>, are no longer prefixed.
Note: From CICS TS v5.2 all JVM profiles located on zFS must have a .jvmprofile suffix.
For more information about the sample profiles, see JVM profiles: options and samples. For a summary of the changes to the JVM profiles, see Changes to JVM profiles .

Back to top

V3.1-V4.2

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.

There are three possible ways to repackage a Java application as one or more OSGi bundles. Each option is explained in full detail in the SDK help, and is summarized in the following procedure.
  1. Check that the Java application is threadsafe. The IBM website developerWorks® has useful information about Java: http://www.ibm.com/developerworks/java/ .
  2. 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.
  3. 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.
  4. Add the CICS-MainClass declaration to the project manifest. Right-click the project name and select PDE Tools > Open Manifest .

    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.

    OSGi package manifest file that shows the attributes and values.

  5. 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.

Back to top

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.

  1. 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.
  2. 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
  3. Restart the JVM server to pick up the properties change.
  4. Deploy the updated application bundle to CICS.
Note:

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.

These packages were previously available without an import statement:
  • org.ietf.jgss
  • org.omg.*
  • org.w3c.*
  • org.xml.*

Back to top

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.

Back to top

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.

Back to top

V5.1

If you use the CICS Liberty security feature, check for restrictions

If you use the CICS Liberty security feature, check whether you need to make changes for the following 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.

Back to top

V5.1

Import classes from JCICS API or IByteBuffer

The JCICS API packaging is changed; the dfjcics.jar and dfjoutput.jar files are replaced by a set of OSGi bundles that run in a JVM server. If you use classes from the JCICS API or the IByteBuffer class, you must import the relevant package into your OSGi bundle manifest when you package a Java application as an OSGi bundle. The following OSGi bundles are provided with CICS:
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.

Back to top

V5.1

If you use the CICS Liberty security feature and do not use autoconfigure, define your own SAF registry.

The Liberty profile server uses a user registry to authenticate a user and retrieve information about users and groups to perform security-related operations, including authentication and authorization. Unless you are using the new distributed identity feature, you must define the System Authorization Facility (SAF) registry as follows:
<safRegistry id="saf"/>
If you are using autoconfigure, this is defined for you.

Back to top



upgrade_java.html | Timestamp icon Last updated: Sunday, 4 June 2017