Troubleshooting Java applications

If you have a problem with a Java™ application, you can use the diagnostics that are provided by CICS® and the JVM to determine the cause of the problem.

1. If you are unable to start a JVM server, check that the setup of your Java installation is correct.
   Use the CICS messages and any errors in the stderr file for the JVM to determine what might be causing the problem.
   1. Check that the correct version of the Java SDK is installed and that CICS has access to it in z/OS® UNIX.
      For a list of supported SDKs, see High-level language support.
   2. Check that the USSHOME system initialization parameter is set in the CICS region.
      This parameter specifies the home for files on z/OS UNIX.
   3. Check that the JVMPROFILEDIR system initialization parameter is set correctly in the CICS region.
      This parameter specifies the location of the JVM profiles on z/OS UNIX.
   4. Check that the CICS region has read and execute access to the z/OS UNIX directories that contain the JVM profiles.
   5. Check that the CICS region has write access to the working directory of the JVM.
      This directory is specified in the WORK_DIR option in the JVM profile.
   6. Check that the JAVA_HOME option in the JVM profiles points to the directory that contains the Java SDK.
   7. Check that SDFJAUTH is in the STEPLIB concatenation of the CICS startup JCL.
   8. If you are using WebSphere® MQ or DB2® DLL files, check that the 64-bit versions of these files are available to CICS.
   9. If you modify DFHAXRO to configure the Language Environment® enclave, ensure that the runtime options do not exceed 200 bytes and that the options are valid.
      CICS does not validate the options that you specify before it passes them to Language Environment. Check SYSOUT for any error messages from Language Environment.
2. If your setup is correct, gather diagnostic information to determine what is happening to the application and the JVM.
   1. Add PRINT_JVM_OPTIONS=YES to the JVM profile.
      When you specify this option, all the options that are passed to the JVM at startup, including the contents of the class paths, are printed to SYSPRINT. The information is produced every time a JVM is started with this option in its profile.
   2. Check the dfhjvmout and dfhjvmerr files for information and error messages from the JVM.
      These files are in the directory that is specified by the WORK_DIR option in the JVM profile. The files might have different names if the STDOUT and STDERR options were changed in the JVM profile.
3. If the application is failing or performing poorly, debug the application.
   • If you receive java.lang.ClassNotFoundException errors and the transaction abends with the AJ05 code, the application might not be able to access IBM or vendor classes in the OSGi framework. For more information about how to fix this problem, see Upgrading.
   • Use the CEDX transaction to debug the application transaction. For a Liberty JVM server, if you are using a URI map to match the inbound application request to an application transaction, debug that transaction. If you use the default transaction CJSA, you must set the MAXACTIVE attribute to 1 on the DFHEDFTC transaction class. This setting is required because a number of CJSA tasks might be running and you might debug the wrong transaction. Do not use CEDX on the CJSA transaction in a production environment.
   • To use a debugger with the JVM server, you must set some options in the JVM profile. For more information, see Debugging a Java application.
   • If you want to determine the status of OSGi bundles and services, use the OSGi console. Set the following properties in the JVM profile: -Dosgi.file.encoding=ISO-8859-1, and-Dosgi.console=host:port where host is the host name of the system the JVM server is running on, and port is a free port on the same system. While the osgi.console.encoding property was designed to allow the OSGi console to use a preferred encoding without putting the whole JVM into that encoding, an outstanding bug in the Equinox OSGi framework prevents its use, instead you must set the file.encoding value to an ASCII based encoding. If you are using an OSGi JVM server, add OSGI_CONSOLE=TRUE to the JVM profile. If you are using a Liberty JVM server, add the osgi console-1.0 feature to the server.xml. Connect to the OSGi console by using a Telnet session with the host and port properties you specified in the JVM profile.
     Note: If you type the exit command into the OSGi console, it will issue a system.exit(0) call to the environment that the JVMSERVER runs in. The command to disconnect your terminal from the OSGi console is disconnect. system.exit(0) is an abrupt stop of all threads and workload, and if left to continue processing, can leave the JVM and CICS in an indeterminate state. CICS is designed to perform an immediate shutdown in this eventuality to avoid subsequent complications. For this reason, it is important to control write access to both the JVM profile, and server.xml. A Liberty JVM server offers further protection by requiring inclusion of the osgiconsole-1.0 feature before the OSGi console is able to run. The OSGi console is primarily a development and debug aid, and is not expected to run in a production environment.
4. If you are getting out-of-memory errors, there might be insufficient 64-bit storage, the application might have a memory leak, or the heap size might be insufficient.
   1. Use CICS statistics or a tool such as IBM Health Center to monitor the JVM. If the application has a memory leak, the amount of live data that remains after garbage collection gradually increases over time until the heap is exhausted.
      The JVM server statistics report the size of the heap after the last garbage collection and the maximum and peak size of the heap. For more information, see Analyzing Java applications using IBM Health Center.
   2. Run the storage reports for Language Environment to find out whether the amount of storage is sufficient.
      For more information, see Language Environment enclave storage for JVMs.
5. If you are getting encoding errors when you install or run a Java application, you might have set up conflicting or an unsupported combination of code pages.
   JVMs on z/OS typically use an EBCDIC code page for file encoding; the default is IBM1047 (or cp1047), but the JVM can use other code pages for file encoding if required. CICS requires an EBCDIC code page to handle character data and all JCICS calls must use an EBCDIC code page. The code page is set in the LOCALCCSID system initialization parameter for the CICS region.
   1. Check the JVM server logs to see whether any warning messages were issued relating to the value of LOCALCCSID.
      If this parameter is set to a non-EBCDIC code page, a code page that is not supported by the JVM, or an EBCDIC code page that is not supported (such as 930), the JVM server uses cp1047.
   2. JCICS calls use the code page that is specified in the LOCALCCSID system initialization parameter.
      If your application expects a different code page, you get encoding errors. To use a different code page for JCICS, set the -Dcom.cics.jvmserver.override.ccsid= parameter in the JVM profile.
   3. If you are using the -Dcom.cics.jvmserver.override.ccsid= parameter in the JVM profile, ensure that the CCSID is an EBCDIC code page. The application must use EBCDIC when it uses JCICS calls.
   4. If you are running SOAP processing in an Axis2 JVM server, ensure that the -Dfile.encoding JVM property specifies an EBCDIC property.
      If you specify a non-EBCDIC code page, such a UTF-8, the web service request fails and the response contains corrupted data.
6. If message DFHSJ0904 is issued and reports a problem similar to the following example, it is likely that you have hit the JVM server's thread limit:

   Exception 'java.lang.Exception: CICSThreadExecutor: no work found for Task 45921. 
   The work this Task was started to perform has already timed-out.' 
   

   Try to address the problem as follows:
   • Increase the THREADLIMIT value on the JVMSERVER resource.
   • If THREADLIMIT is already set to the maximum permitted value, then you might be attempting to run more work than a single JVM server can handle. Consider balancing the workload between multiple JVM servers or multiple regions.

     Alternatively, your CICS system might be unresponsive because of other constraints. Follow the standard procedures to diagnose performance problems. See Improving the performance of a CICS system.