Troubleshooting Liberty JVM servers and Java web applications

Avoiding problems

CICS uses the values of the region APPLID and the JVMSERVER resource name to create unique file and directory names on the zFS file system. Some of the acceptable characters have special meanings in the UNIX System Services shell. For example, the dollar sign ($) means the start of an environment variable name. Avoid using non-alphanumeric characters in the region APPLID and JVM server name. If you do use these characters, you might need to use the backslash (\) as an escape character in the UNIX System Services shell. For example, if you called your JVM server MY$JVMS:

cat CICSPRD.MY\$JVMS.D20140319.T124122.dfhjvmout

Unable to start Liberty JVM server

1. If you are unable to start a Liberty JVM server, check that your setup is correct. Use the CICS messages and any errors in the Liberty messages.log file that is located below WLP_OUTPUT_DIR to determine what might be causing the problem.
2. Check that the -Dfile.encoding JVM property in the JVM profile specifies either ISO-8859-1 or UTF-8. These are the two code pages that are supported by the Liberty profile server. If you set any other value, the JVM server fails to start.

Web application is not available after it is deployed to the dropins directory

1. If you receive a CWWK0221E error message in dfhjvmerr, check that you set the right values for the host name and port number in the JVM profile and server.xml. This error message indicates that the port number or host name that are specified are incorrect. The host name might be invalid or the port number might be in use.

CICS CPU is increased after a Liberty JVM server is enabled

1. The Liberty JVM server is scanning the dropins directory too frequently and causing too much I/O and CPU usage. The frequency that the Liberty JVM server scans the dropins directory for applications is configurable. The default interval that is supplied in the configuration templates is 5 seconds, but you can increase this value or disable the application scan.

   To fix this problem, edit the following XML in the server.xml file:

   <config monitorInterval="5s" updateTrigger="polled"/>
   <applicationMonitor updateTrigger="disabled" pollingRate="5s" dropins="dropins" dropinsEnabled="false"/>

   If you install your web applications in CICS bundles, do not disable polling in the <config> element, but disable the application scan. For information on how to edit this setting, see Controlling dynamic updates.

Application not available

1. You copy a WAR file into the dropins directory but your application is not available. Check the Liberty messages.log file for error messages. If you receive the CWWKZ0013E error message, you already have a web application running in the Liberty JVM server with the same name. To fix this problem, change the name of the web application and deploy to the dropins directory.

Web application is not requesting authentication

You configured security, but the web application is not requesting authentication.

1. Although you can configure CICS security for web applications, the web application uses security only if it includes a security restraint in the WAR file. Check that a security restraint was defined by the application developer in the web.xml file in the dynamic web project.
2. Check that the server.xml file contains the correct security configuration information. Any configuration errors are reported in dfhjvmerr and might provide some useful information. If you are using CICS security, check that the CICS security feature is specified. If CICS security is switched off, check that you specified a basic user registry to authenticate application users.
3. Check that server.xml is configured either for <safAuthorization> to take advantage of EJBRoles, or for a local role mapping in an <application-bnd> element. The <application-bnd> element is found with in the <application> element in server.xml or installedApps.xml. The default security-role added by CICS for a local role mapping is 'cicsAllAuthenticated'.

Web application is returning an HTTP 403 error code

The web application is returning an HTTP 403 error code in the web browser. If you receive an HTTP 403 authorization failure, either your user ID is revoked or you are not authorized to run the application transaction.

1. Check the CICS message log for the error message ICH408I to see what type of authorization failure occurred. To fix the problem, make sure that the user ID has a valid password and is authorized to run the transaction.
2. If the application is retuning an exception for the class com.ibm.ws.webcontainer.util.Base64Decode, check dfhjvmerr for error messages. If you see configuration error messages, for example CWWKS4106E or CWWKS4000E, the server is trying to access configuration files that were created in a different encoding. This type of configuration error can occur when you change the file.encoding value and restart the JVM server. To fix the problem, you can either revert to the previous encoding and restart the JVM server, or delete the configuration files. The JVM server re-creates the files in the correct file encoding when it starts.

Web application is returning an HTTP 500 error code

The web application is returning an HTTP 500 error in the web browser. If you receive an HTTP 500 error, a configuration error occurred.

1. Check the CICS message log for DFHSJ messages, which might give you more information about the specific cause of the error.
2. If you are using a URIMAP to run application requests on a specific transaction, make sure that the URIMAP is using the correct transaction.
3. If the URIMAP is using the correct transaction, make sure that the SCHEME and USAGE attributes are set correctly. The SCHEME must match the application request, either HTTP or HTTPS. The USAGE attribute must be set to JVMSERVER.

Web application is returning an HTTP 503 error code

The web application is returning an HTTP 503 error in the web browser. If you receive an HTTP 503 error, the application is not available.

1. Check the CICS message log for DFHSJ messages for additional information.
2. Make sure that the TRANSACTION and URIMAP resources for the application are enabled. If these resources are packaged as part of the application in a CICS bundle, you can check the status of the BUNDLE resource.
3. The request might have been purged before it completed. The errors messages in the log describe why the request was purged.

The web application is returning exceptions

The web application is returning exceptions in the web browser; for example the application is retuning an exception for the class com.ibm.ws.webcontainer.util.Base64Decode.

1. Check the dfhjvmerr for error messages.
2. If you see configuration error messages, for example CWWKS4106E or CWWKS4000E, the server is trying to access configuration files that were created in a different encoding. This type of configuration error can occur when you change the file.encoding value and restart the JVM server. To fix the problem, you can either revert to the previous encoding and restart the JVM server, or delete the configuration files. The JVM server re-creates the files in the correct file encoding when it starts.

Error message CWWKB0109E

If the Liberty server fails to shut down cleanly, the next Liberty JVM server with WLP_ZOS_PLATFORM=TRUE will write the error message CWWKB0109E to the messages.log file. You do not need to fix this error and it can be ignored.

Using the productInfo script to verify integrity of the Liberty profile

You can verify the integrity of the Liberty profile installation after you install CICS or applying service, by using the productInfo script.

1. Change directory to the CICS USSHOME directory.
2. As productInfo uses Java, you must ensure that Java is included in your PATH. Alternatively, set the JAVA_HOME environment variable to the value of JAVA_HOME in your JVM profile, for example:

   export JAVA_HOME=/usr/lpp/java/J7.0_64 

3. Run the productInfo script, supplying the validate option wlp/bin/productInfo validate. No errors should be reported. For more information about the Liberty profile productInfo script, see Verifying the integrity of Liberty profile installation.

Using the wlpenv script to run Liberty commands

You might be asked by IBM service to run one or more of the Liberty profile supplied commands, such as productInfo or server dump. To run these commands, you can use the wlpenv script as a wrapper to set the required environment. The script is created and updated every time that you enable a Liberty JVM server after the JVM profile has been successfully parsed. Because the script is unique for each JVM server in each CICS region, it is created in the WORK_DIR as specified in the JVM profile and is called APPLID.JVMSERVER.wlpenv, where APPLID is the value of the CICS region APPLID and JVMSERVER is the name of the JVMSERVER resource.

./CICSPRD.DFHWLP.wlpenv productInfo version

./CICSPRD.DFHWLP.wlpenv server dump --archive=package_file_name.dump.pax  --include=heap

For more information about the Liberty commands, see Liberty profile: productInfo command in WebSphere Application Server for z/OS and Generating a Liberty profile server dump from the command prompt