Known issues and limitations

Known issues or limitations that you might encounter in specific system environments, or configurations.

Some of the problems that are described here might not be limitations with the release because instructions are provided to work around problems, where possible.

Items that are new for this release

Issue with the Java 21 keytool
When you use the tool zseckeytool -exportcert, it is recommended to use the -file option along with a file name. This helps ensure that the exported certificate is untagged and DER encoded. To maintain the DER encoding, it is crucial to keep the file untagged and avoid converting it to a different format unintentionally.

If you prefer PEM encoding, you can use the -rfc option along with the -file option. Use the command chtag -tc ISO8859-1 to tag the certificate. To read the PEM encoded file, make sure that it remains tagged as text and ISO8859-1, and set the appropriate LE auto convert environment variables.

For DER encoded certificate files, Java 17 keytool or earlier versions are recommended for printing. A known issue exists with Java 21 keytool where certain information might not be printed correctly.

When you print the PEM encoded certificate files, you can also use the OpenSSL tool for assistance.

In summary, be mindful of the encoding and tagging options when you work with the zseckeytool -exportcert tool to help ensure accurate and consistent printing of the certificate.

Limitations with applications that use Foreign Function and Memory API
The Foreign Function and Memory (FFM) API is a preview feature in Java 21. The following are the known limitations of the feature's support on z/OS.
  • When native foreign functions call the Java code by using the upcall or Java code calls the foreign functions by using the downcall stubs, certain calls that involve struct arguments might not be setup correctly causing incorrect behavior of the program.
  • Lookup of native variable symbols from native libraries by using java/lang/foreign/SymbolLookup.loaderLookup().find() APIs might result in an unexpected exception java.util.NoSuchElementException.
  • Varargs support on downcalls might not work as expected.
  • When Java code that is called from foreign function encounters an exception, the application might exit unexpectedly.
Class java.awt.Robot is not supported
The java.awt.Robot class is not supported on z/OS systems. Java programs that use the Robot class might not run correctly on z/OS systems.

Items from previous releases that still apply

Circular loading error when you use SAF key rings and a Java™ security manager
This error occurs in the following scenario:
  • You have a Java application that uses one of the IBM implementations of the URLStreamHandlerProvider API (for example, com.ibm.crypto.hdwrCCA.provider.safkeyring.Provider) to create a URLStreamHandler instance by using any of the following supported SAF key ring URLs: safkeyringjce, safkeyringjcehybrid, or safkeyringjcecca.
  • You run the Java application with a security manager enabled (for example, by specifying -Djava.security.manager on the Java command line).
The application throws a message similar to the following example:
Exception in thread "main" java.util.ServiceConfigurationError: java.net.spi.URLStreamHandlerProvider:
Provider com.ibm.crypto.ibmjcehybrid.provider.safkeyring.Provider could not be instantiated
The stack trace contains further information: 
Caused by: java.lang.Error: Circular loading of URL stream handler providers detected

This error is related to the use of the security manager. To avoid this issue, use the safkeyring URL with the java.protocol.handler.pkgs system property, as described in Accessing a RACFInputStream and RACFOutputStream instance by using the URLStreamHandler class.

Note: The SecurityManager API was deprecated in OpenJDK17 and might be removed in a future release of the IBM SDK.
Some single-file source code programs are not supported

Currently, you cannot run Java programs that are supplied as a UNIX script shebang file, as described in JEP 330.

jlink tool attempts to set the APF-authorized attribute on libj9ifa29.so to fulfill zIIP eligibility
When you use the jlink tool to create a native runtime image, the tool tries to set the APF-authorized attribute on the libj9ifa29.so library to make sure that the Java application remains eligible for processing by the IBM® System z Integrated Information Processor (zIIP). If you are not authorized to perform the APF operation, a warning message is issued:
Warning: APF authorization failed for lib/default/libj9ifa29.so
For information about the permissions that are needed to set the APF-authorized attribute, see the documentation for your version of z/OS. For example, Controlling who can set the APF-authorized attribute.
Limitation of class path length

If there are more than 2031 characters in your class path, the shell truncates your class path to 2031 characters. If you need a class path longer than 2031 characters, use an options file. For details, see @argfile in https://docs.oracle.com/en/java/javase/11/tools/java.html.

Messages written using stout or stderr might not be redirected when freopen() is used
Messages that the JVM writes to stdout or stderr might not be redirected to the new file if the Java app uses the C/C++ freopen() function to redirect stdout or stderr streams from a file of one type to the other. To fix this problem, set the com.ibm.writeToStandardOutputsUsingStreams system property to true when you start the JVM. This property specifies that the output is written by using file streams, which support the redirection of data between MVS datsets and Unified Storage Server (USS) Z File System (zFS) files.
Note: This setting also changes the default buffering behavior from no buffering to line buffering, and output might not be produced promptly. To counter this issue, disable buffering by using the setbuf() or setvbuf() functions after you call the freopen() function.

Other issues

If you find a problem that you are unable to solve, see Java SDK troubleshooting for advice and information about how to raise problems.