IBM Time Zone Update Utility for Java (JTZU)

Readme

Last updated 11 November 2009.

(c) Copyright International Business Machines Corporation, 1999, 2009. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Introduction
Downloading and installing JTZU
Getting started with JTZU
Advanced features
Restoring changes applied by JTZU
Known limitations
JTZU reference information

Introduction

The IBM Time Zone Update Utility for Java (JTZU) updates the time zone information in IBM-supplied releases and service refreshes of the Java SDK and JRE. With this tool, you can adopt changes to DST when you are unable to apply a service refresh, or when a service refresh is not yet available that incorporates the time zone changes you need.

How JTZU works

Java SDKs and JREs calculate their time zone information using a set of rules for time zone offsets contained in tables. When you use JTZU to update installed SDKs or JREs, the time zone tables are replaced.

JTZU obtains updated time zone information from the Olson time zone database. Olson data updates are identified by a unique string; for example, tzdata2009x, where x is one of a series of refreshes delivered in 2009. Each version of JTZU is given a similar identifier to reflect the level of time zone data. For example, JTZU v1.6.9f delivers the time zone information available in tzdata2009f.

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.6.9f will update any JRE that has a time zone data level of tzdata2009e 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 Olson time zone updates for Java JRE and SDK service refreshes for IBM products

Supported platforms

Note that HP-UX 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

SDKs and JREs detected but not patched by JTZU

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 developerWorks: JTZU download page. 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

Note these prerequisites:

Specifying the JRE used to run JTZU

You must decide which JRE the JTZU tool will use 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 you use will depend 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:

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:
  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:
  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:
  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:

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\java142 and all its subdirectories.

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

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 will 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.

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

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:
  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:
  3. Restart your JREs.

Restoring changes applied by JTZU

Java 1.4.2 and 5.0 (AIX, Linux, Windows, and z/OS): JTZU makes a backup of the core.jar file in the jre/lib directory.

  1. Ensure that the jre/lib/core.jar_jtzubackup file exists.
  2. Delete the jre/lib/core.jar file.
  3. Rename the jre/lib/core.jar_jtzubackup file to jre/lib/core.jar.

Java 6.0 (AIX, Linux, Windows, and z/OS) and Java 1.4.2, 5.0 and 6.0 (HP-UX and Solaris): 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, 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.

For further problems and information on diagnosing problems, see IBM Time Zone Update Utility (JTZU): known problems and diagnostic information.

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 1.4 and above SDKs and JREs patched by JTZU can be used with the old 3-character time zone identifiers. See Java Daylight Saving Time: Known problems and workarounds for more information.