Java SDK Time Zone Update Utility, readme

When JTZU is processing an IBM-supplied SDK or JRE, it checks the level of the time zone data contained in the time zone tables. If the SDK or JRE contains an earlier level of time zone information, JTZU updates the SDK or JRE. For example, JTZU v1.7.21a will update any JRE that has a time zone data level of tzdata2021a or earlier.

JTZU uses the same time zone updates that are incorporated into IBM-supplied releases and service refreshes of the SDK and JRE. See Java SDK Olson time zone updates.

Supported platforms

• AIX on POWER 32-bit / 64-bit
• HP-UX PA-RISC 32-bit / 64-bit
• HP-UX Itanium 32-bit / 64-bit
• Solaris SPARC 32-bit / 64-bit
• Solaris AMD64 32-bit / 64-bit
• Linux AMD64/EM64T
• Linux on AArch64
• Linux on POWER 32-bit / 64-bit
• Linux on system Z 31-bit / 64-bit
• macOS AMD64/EM64T
• Windows Intel 32-bit / 64-bit
• Windows AMD64/EM64T
• z/OS 31-bit / 64-bit

Note that HP-UX, macOS, and Solaris platforms are supported only when embedded with an IBM product.

JTZU does not support Java on IBM i platforms. To update Java on IBM i, refer to Updating Java for Daylight Saving Time (DST) changes on IBM i platforms.

SDKs and JREs detected and patched by JTZU

• IBM Semeru Runtimes 8, 11 and 17 releases in Windows, AIX, Linux, macOS, and z/OS platforms
• IBM SDK 7, 7.1, 8, 11 and 17 releases in Windows, AIX, Linux, macOS, and z/OS platforms
• IBM-modified Java 7, and 8 SDKs and JREs on Solaris and HP-UX that are shipped as part of an IBM-licensed product
• IBM-modified Java 8 SDKs and JREs on macOS that are shipped as part of an IBM-licensed product

SDKs and JREs detected but not patched by JTZU

• Any unmodified Oracle-supplied (Windows, Linux, Solaris) or HP-supplied (HP-UX) base Java releases, including instances shipped in products from companies that have been subsequently acquired by IBM, for example, Informix IDS.
• Any instances supplied by other Java Technology providers.

Note: These SDKs and JREs are detected by the JTZU tool when running with the DISCOVERONLY=YES option in command-line mode. When running interactively, JTZU does not detect or patch these SDKs and JREs.

Downloading and installing JTZU

JTZU is available from IBM Support: Java SDK Time Zone Update Utility. Follow these instructions to download and install the tool.

1. Create a local directory for JTZU; for example, /tmp/jtzu or c:\jtzu.
2. Download the zip file to the JTZU directory. Use binary transfer mode, where applicable.
3. Extract the files. Use the jar utility where available: jar -xvf filename, where filename is the compressed zip file.
4. On AIX, z/OS, Linux, Solaris, and HP-UX platforms, you must change the file permissions to allow JTZU to run from the command line. At a shell prompt, type chmod 755 runjtzu.sh

Getting started with JTZU

Prerequisites

The following prerequisites apply:

• You need a Java SDK or JRE installation to run JTZU.
• You must run JTZU as a user with root or administrator privileges to allow it to find and update all the Java instances on the machine.
• When you update an SDK or JRE using JTZU, ensure that the SDK or JRE is not being used by any applications. If the SDK or JRE is in use, you might encounter errors as described in Known limitations.
• To run the utility using the GUI on AIX, z/OS, Linux, Solaris, and HP-UX platforms, you must be running an X server.

Specifying the JRE used to run JTZU

You must decide which JRE the JTZU tool uses to run the update process. This JRE can be the same one that you want JTZU to update. When you have decided which JRE to use, you must update the JTZU settings file to specify the location of the JRE. Edit the JTZU settings file and set JAVA_HOME to match the directory path of the chosen JRE. The name of the settings file and program file for your platform is shown in the table:

Platform	JTZU settings file	JTZU program file
Windows	runjtzuenv.bat	runjtzu.bat
Other platforms	runjtzuenv.sh	runjtzu.sh

Deciding how to update your Java SDKs and JREs

You can use JTZU in a number of ways to search for and update your Java SDKs and JREs. You might need to do an initial search for all the SDKs and JREs on your systems and validate their existing time zone information. You can tailor the search faciltity to search specific directories on your system.

When you are ready to update your SDKs or JREs, you can run JTZU to update individual instances or multiple instances on a local or network drive. The update process can be run automatically without user intervention, or you can control which JREs and SDKs are updated by JTZU.

The method that you use depends on the number and variety of Java instances that you must update. The flexibility built into the tool means that you can adapt the way it runs to suit your needs.

A number of scenarios are provided as examples for using JTZU:

• How to update an SDK or JRE at a known location
• How to search for SDKs and JREs
• How to search for SDKs and JREs, updating supported releases

JTZU records information about the search paths, the JREs that are detected, and the JREs that are updated in LogFile.log. Errors are also logged to this file.

How to update an SDK or JRE at a known location

Follow these steps:

1. Stop the JRE that you are going to update.
2. Edit the JTZU settings file:
   • Set NOGUI=false
   • The DISCOVERONLY setting is not used.
3. Run JTZU.
4. When prompted, select Interactive mode. Click Start.
5. Enter the location of the JRE in the text box or use the Browse button to select one.
6. Click Update to perform the time zone update for the selected JRE.
7. Restart the JRE.

You do not need to reboot your system after updating SDKs or JREs.

How to search for SDKs and JREs

Use this procedure to search for all JREs and SDKs on your system. The results are written to Logfile.log. Any SDKs and JREs that can be updated will be shown in the SDKList.txt file. The search process can take a long time, depending on the size of your system. It is not necessary to stop your JREs during the discovery process.

1. Edit the JTZU settings file:
   • Set NOGUI=true.
   • Set DISCOVERONLY=true.
2. Ensure that the DirectorySearch.txt file contains the value all as the only record. This step is important on z/OS because the file can be corrupted.
3. Run JTZU.

By default, JTZU searches the entire file system.

How to search for SDKs and JREs, updating supported releases

This procedure uses the JTZU GUI to locate all JREs and SDKs on a system and update supported instances, where necessary.

1. Stop all active JREs on the system.
2. Edit the JTZU settings file:
   • Set NOGUI=false.
   • The DISCOVERONLY setting is not used.
3. Run JTZU.
4. When prompted, select Non-interactive mode. Click Start.
5. Progress is displayed in a new window. When complete, restart the JREs.

The GUI displays all SDKs and JREs supported for updating in the top section, and all SDKs and JREs that require updating in the bottom section. The GUI does not display SDKs and JREs that JTZU cannot patch. You do not need to reboot your system after updating SDKs or JREs.

Advanced features

You can use the advanced features of JTZU to perform these tasks:

• Selective searching
• Selective updating
• Silent updating

Each feature can be used independently or they can be used together.

Selective searching

You can perform a selective search of your directories by configuring the DirectorySearch.txt file. Edit this file to restrict where JTZU searches for JREs on your system. Each entry must begin on a new line. You can use network drives or mount points to specify remote systems.

Adding and removing directories

You can add and remove locations from the search by placing a + or - before a directory name. There must not be a space between the + or - and the name of the directory.

For example, on Windows, a DirectorySearch.txt file containing the directories shown causes JTZU to recursively search the contents of the c:\programs directory, excluding c:\programs\ibm\java8 and all its subdirectories.

• +c:\programs
• -c:\programs\ibm\java8

On other platforms, the equivalent format of the DirectorySearch.txt file must be:

• +/usr
• -/usr/bin

The all keyword

If the all entry is the first entry in the file, JTZU searches everywhere on the system except for specified exclusions. If the all entry is not in the file, or is not the first entry in the file, JTZU searches only in specified locations.

For example, on Windows, a DirectorySearch.txt file containing the directories shown causes JTZU to search the entire system except the c:\workarea directory.

• all
• -c:\workarea

On other platforms, the equivalent format of the DirectorySearch.txt file must be:

• all
• -/proc

Directories to exclude on AIX, z/OS, Linux, Solaris, and HP-UX platforms

By default, JTZU does not search the /proc directory. This directory is excluded because it contains dynamically generated directories that might form an infinite loop. You might also consider excluding the /dev and /sys directories depending on your platform. In addition, the /etc, /tmp, and /var directories are unlikely to contain JREs.

Selective updating

To update a subset of SDKs or JREs on your system, you must first run JTZU in discovery mode to produce a complete list of SDKs and JREs on your system. Follow the steps detailed in the scenario How to search for SDKs and JREs. JTZU records all the SDKs and JREs that can be updated in the SDKList.txt file.

1. Edit the SDKList.txt file and remove any entries that you do not want to patch.
2. Stop the JREs that are going to be patched.
3. Run JTZU with the JTZU settings file containing the values:
   • NOGUI=true
   • DISCOVERONLY=false
4. Restart your JREs.

Silent updating

You can update all the instances supported for updating without any user interaction by running JTZU in SilentPatch mode.

1. Stop the JREs that are going to be updated.
2. Run JTZU with the JTZU settings file containing the values:
   • NOGUI=true
   • DISCOVERONLY=false
   • SILENTPATCH=true
3. Restart your JREs.

Restoring changes applied by JTZU

Java 8, 11 and 17: JTZU makes a backup of the tzdb.dat file. For Java 8 the backup is in the jre/lib directory. For Java 11 and 17 the backup is in the in the lib directory.

1. Ensure that the tzdb.dat and tzdb.dat_jtzubackup files exist.
2. Delete the tzdb.dat file.
3. Rename the tzdb.dat_jtzubackup file to tzdb.dat.

Java 7, and 7.1: JTZU makes a backup of the zi directory in the jre/lib directory.

1. Ensure that the jre/lib/zi_jtzubackup directory exists.
2. Delete the jre/lib/zi directory.
3. Rename the jre/lib/zi_jtzubackup directory to jre/lib/zi.

Known limitations

See Java Daylight Saving Time: Known problems and workarounds for general information relating to DST. The following limitations apply to JTZU:

Patching the JRE used to run JTZU

On AIX, Linux, macOS, Windows, and z/OS, attempting to patch the JRE used to run JTZU more than once results in the following error message:

java.lang.InternalError: jzentry == 0, jzfile = 3259568, total = 2859, name = C:\cn142-20060217\sdk\jre\lib\core.jar,
i = 2541, message = invalid LOC header (bad signature)
at java.util.zip.ZipFile$2.nextElement(ZipFile.java(Compiled Code))
at java.util.jar.JarFile$1.nextElement(JarFile.java(Compiled Code))
at JTZUVersionCheck.retrieveCurrentVersion(JTZUVersionCheck.java(Compiled Code))
at JTZUVersionCheck.(JTZUVersionCheck.java:43)
at JTZUUpdater.updateTimeZoneInformation(JTZUUpdater.java:65)
at JTZUInteractive$JTZUInteractiveWorkerThread.updateTimeZoneInformation(JTZUInteractive.java:322)
at JTZUInteractive$JTZUInteractiveWorkerThread.run(JTZUInteractive.java:186)

Avoid this error by restarting JTZU after patching the JRE for the first time.

JREs might be flagged as corrupt after patching

If you patch a JRE using SMP/E on z/OS or installp on AIX, the SMP/E or installp utilities might flag the JRE as corrupt or inconsistent. The message is expected because you have modified the JRE.

JTZU reference information

You can use these settings in the JTZU settings file:

JAVA_HOME	Location of the JRE that you will use to run the utility. It must be a JRE or the JRE contained in an SDK.
NOGUI	When set to true, JTZU runs in command-line mode. When set to false, JTZU runs with a graphical user interface. The default is false.
DISCOVERONLY	When set to true, JTZU discovers IBM JREs and stores their locations in the SDKList.txt file. When set to false, JTZU discovers IBM JREs and updates them based on their locations in the SDKList.txt file. The default is true.
SILENTPATCH	When set to true, JTZU updates the SDKs and JREs without any user interaction in command-line 'Patch' mode.
BACKWARDCOMPATIBILITY	When set to true, Version 7 and later SDKs and JREs patched by JTZU can be used with the old 3-character time zone identifiers.