Background

   Here at Phoenix Software International, we use Java heavily, both for internally facing tools and in our products. In this article I will focus on my experience as it relates to developing our Java-based product offerings: (E)JES Web and Entrypoint. Both of these applications run inside web application containers (Embedded Tomcat in the case of Entrypoint, and Tomcat/OpenLiberty for (E)JES Web).
(E)JES Web is currently compiled with Java 8 to maintain backward compatibility with previous releases of z/OS, and supports Semaru 11, 17, and 21. The product provides both an interactive web user interface and REST web services to the (E)JES product. Entrypoint is a data entry system that was originally developed off-platform and is in the process of being ported to z/OS. The latest releases are built using Java 21, with earlier versions using Java 11.
Anyone who has been through the process of migrating from Java 8 to Java 11 will tell you that the required engineering effort is not trivial. The differences between Java 11 and 17, however, had less of an impact, primarily involving changes to environment variables, JCL and/or additional arguments to the JVM.

Challenges
   For us, the migration from Java 17 to Java 21 at first appeared to be even more straight-forward than the move from 11 to 17. We duly changed the file system paths to point to the new JVM and updated the load library and module references in our JCL accordingly. After the jobs were submitted, the applications came up as expected. Everything looked perfect until we inspected the job output, where we found that portions of the output consisted of unreadable characters. Stranger still, the output was correct when these applications were launched from Unix System Services (via SSH or OMVS), or using BPXBATCH in JCL, which meant the issue only appeared when using the JZOS launcher.
   One of the major changes in Semaru 21 is JEP 400 “UTF-8 by Default”.  In previous releases, “the JDK chooses the default charset at startup based upon the run-time environment: the operating system, the user's locale, and other factors.” On the mainframe, this generally means IBM-1047 or IBM-273. Semaru 21 and JZOS offer several properties, VM arguments, and environment variables to make the transition seamless, and IBM provides excellent documentation, particularly in the ‘Controlling output encoding’ page.
   Importantly, neither of these applications use z/OS native character encodings and instead use UTF-8 and ISO-8859-1, respectively. We immediately suspected that the issue was related to the changes introduced by JEP 400, but this alone didn’t explain why the output was correct in all cases except when the JZOS launcher was used, and even then, why only portions of it were unreadable.
   Further investigation revealed that the ‘garbled’ portions of the output were limited to java.util.Logger output, while stdout and stderr were correct. We created a simple Java program and supporting JCL to isolate the issue and compare the behavior of different versions of Semaru (11, 17, and 21) with the same code. With the isolated test code and results in hand, we reported the issue to IBM, who were able to confirm that the problem was in the JZOS Launcher. In November of 2025, APAR PH68459 was released (https://www.ibm.com/support/pages/apar/PH68459) which solved the issue.

Benefits 
   The Java platform is very much alive on z/OS. With each new release features are being added, security tightened, and older features deprecated. Keeping up to date with the latest versions allows us to integrate these changes into our products in smaller increments which reduces our technical debt over the long-term. It also offers the opportunity to take advantage of new features and technologies that are becoming available and is one of the reasons our products remain state-of-the-art.
   A great example of the new features available in Semaru 21 is the Java Foreign Functions and Memory API (JFFM). This API provides similar functionality to the Java Native Interface (JNI), but more closely resembles the native call interfaces used by other languages such as ‘ctypes’ in Python or the ‘Foreign Function Interface’ in Node.js. While JNI will be with us for the foreseeable future, enhancement proposals such as JEP 472 (“Prepare to Restrict the Use of JNI”) mean that the use of JFFM over JNI will, at the very least, be considered a best-practice in the future.
   For us, this is extremely relevant. As mentioned, (E)JES Web is the web interface for EJES, providing both REST services and an interactive user interface. The architecture is centered around calls to the native EJES API that are facilitated by a JNI wrapper library that also handles dynamic memory management, module loading/unloading, error handling, and synchronization. By migrating to Semaru 21 we have been able to begin development of the next generation of (E)JES API which will enable the product to support not only JFFM, but also opens the door to supporting other languages such as Python, Go, and Node.js in the future.

Final Thoughts
   Overall, our experience with Semaru 21 has been a very positive one. While it was not without hiccups along the way, IBM has proven itself to be an excellent partner that is committed to ensuring that the mainframe ecosystem continues to be the world-class platform for mission-critical applications.