Controlling output encoding

In a Java™ VM, regardless of the operating system, strings and characters are represented in Unicode. Because different operating systems use different character set encoding natively, the following mechanisms are used to control encoding:

  • The Java file.encoding system property. This property specifies the default character to be used when characters are converted to or from bytes. The default file encoding of Semeru Runtime Certified Edition for z/OS 21 is UTF-8 but other encoding formats such as EBCDIC variants like IBM-1047 or IBM-273 on z/OS® and ASCII-based encoding like Cp1242 or ISO8859-1 on Windows and UNIX can be specified by setting the system property -Dfile.encoding on the command line when you run your Java application. For more information, see Java SDK options and system properties.
  • The JZOS batch launcher redirects the JVM’s System.out and System.err streams to the //STDOUT and //STDERR DD data sets. When these streams are redirected, JZOS modifies them to use the encoding that is returned by the Zutil.getDefaultPlatformEncoding() method. By default, this encoding is the encoding of the current locale, which for many installations is UTF-8 (assuming that the LANG=C system environment variable is set). You can modify this default by exporting the JZOS_OUTPUT_ENCODING environment variable in the //STDENV configuration script.

    Because the java.io.PrintStream class also supports interfaces for writing raw bytes, the batch launcher also transcodes raw bytes from the current Java file encoding to the JZOS default operating system encoding. This transcoding is only available if both code sets are single-byte encodings, and can be disabled by setting the environment variable JZOS_ENABLE_OUTPUT_TRANSCODING=false.

  • A Java coding best practice is to not assume a particular default file.encoding value, however it is common for Java code to assume an ASCII file encoding. This assumption can happen in subtle ways, such as by generating or parsing XML without specifying an encoding. It is often necessary to run these applications with an ASCII file encoding of ISO-8859-1. Some widely used Java applications, such Apache Tomcat, include code that requires this setting.
  • When an application runs with an ASCII default file encoding, it must specifically use an EBCDIC encoding when it accesses MVS data sets that are encoded in EBCDIC. Use the Zutil.getDefaultPlatformEncoding() method to obtain the current operating system encoding, for this purpose.

Best practices

  1. Avoid writing code that assumes a default file.encoding value, but if you need to run code that does, specify the -Dfile.encoding=ISO-8859-1 system property on the command line when you run the Java application. This setting does not cause a performance impact because internal Unicode must be converted to something anyway.
  2. When an application accesses MVS data sets, specify the encoding by using the Zutil.getDefaultPlatformEncoding() method. The JZOS Toolkit portable file I/O classes are already implemented to use this operating system encoding for MVS data sets. For more information, see Operating system independent text file I/O with the FileFactory class.