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 likeIBM-1047
orIBM-273
on z/OS® and ASCII-based encoding likeCp1242
orISO8859-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 isUTF-8
(assuming that theLANG=C
system environment variable is set). You can modify this default by exporting theJZOS_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 ofISO-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
- 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. - 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.