IBM Time Zone Update Utility for Java (JTZU)

Last updated 05 Dec 2006.

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

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

Contents

Introduction

The IBM Time Zone Update Utility for Java (JTZU) updates an IBM-supplied Java installation with the latest time zone information.

It provides a method of applying preventive service to IBM products that imbed the Java SDK or JRE. It avoids the need to carry out a total replacement of the SDK or JRE and executes independently of any Fix Packs or Service Packs supplied by IBM products. It will update only the time zone information and apply no other fixes.

With time zone arrangements now changing at more frequent intervals, JTZU provides a method for customers unable to wait for the delivery of time zone fixes via conventional service processes to keep their systems up to date with time zone data changes.

How JTZU works

JTZU uses data from the Olson Time Zone data tables (URL: http://www.twinsun.com/tz/tz-link.htm) to update the equivalent information contained in the Java SDKs and JREs. From Java 1.4 onwards, the SDKs and JREs calculate their time zone information using a set of rules for time zone offsets in tables very similar to the Olson tables. In Java 1.3.1 and earlier releases, these rules are encoded inside the Java class logic. When JTZU is used to update installed SDKs or JREs, it replaces either the timezone tables (for Java 1.4 and later releases) or the Java class file containing the timezone logic (Java 1.3.1 and earlier).

The level of time zone data is identified in the same way as in the Olson database; for example tzdata2006x, where the "x" is one of a series of refreshes delivered in 2006. The level of the time zone data table is reflected in the version level of JTZU - for example JTZU Version 1.0.6p contains timezone data at the level of Olson's tzdata2006p.

When JTZU is processing an IBM-supplied SDK or JRE, it first checks the level of the time zone data in it and then performs an update if the SDK or JRE is at an earlier time zone data level than the target level contained in JTZU. For example, if the target level is tzdata2006p, any JRE with a time zone data level of tzdata2006o or earlier will be updated.

SDKs and JREs recognised and processed by JTZU

SDKs/JREs recognised by JTZU:

• IBM supplied 1.2.2, 1.3.1, 1.4.0, 1.4.1, 1.4.2, and 5.0 releases on Windows, AIX, Linux, z/OS, and OS/2 platforms.
• IBM-modified Java 1.4.x and 5.0 "hybrids" on Solaris and HP-UX shipped as part of an IBM-licensed product.

SDKs and JREs not recognised by JTZU:

• IBM iSeries (i5/OS) platforms.
• IBM-supplied releases prior to Java 1.2.2 on Windows, AIX, Linux, z/OS and OS/2 platforms.
• Sun's Java 1.3.1 on Solaris and HP's Java 1.3.1 on HP-UX, even when these are shipped as part of an IBM-licensed product.
• Any unmodified Sun-supplied (Windows, Linux, Solaris) or HP-supplied (HP-UX) base Java releases, including such instances shipped in products delivered by companies that have been subsequently acquired by IBM (for example, Informix IDS).
• Any instances supplied by other Java Technology providers.

Downloading and Installing JTZU

1. Download JTZU as a single ".zip" package from the IBM developerWorks site: www.ibm.com/developerworks/java/jdk/dst/index.html. Use binary transfer mode where applicable.
2. Create a directory for the files used to run JTZU. For example /tmp/jtzu or c:\jtzu
3. Unzip the JTZU package into this directory.
   Caution: Some versions of the unzip tool on AIX do not preserve case. If the utility extracts with all lower case letters, extract the utility useing the jar tool instead.
4. On non-Windows platforms, you will need to set the executable bit for the utility. At a shell prompt, type:

   chmod 755 runjtzu.sh

Running JTZU

Prerequisites

• You need a Java SDK or JRE installation (1.3.1 or later) to run the JTZU utility.
• You must run JTZU as a user with root or administrator privileges to allow it to find and patch all the Java installations on the machine.
• When you patch 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 being used, you might encounter errors as described in Known limitations.
• To run the utility using the GUI on non-Windows platforms, you must be running an X server.

Specifying the JRE used to run the Utility

Before running JTZU, you must decide which JRE to use to run it. This may be the same JRE as the one that the Utility is going to patch. You specify the location of the JRE used to run the utility in the JTZU Settings file. This JRE must be at a level of Java 1.3.1 or higher. If you are updating a 1.2.2 JRE or SDK, you must use a 1.3.1 (or higher level) JRE to drive the utility. If not available on the local machine, this JRE can be located on a network drive.

NOTE: When running on Windows or Linux platforms, this JRE must be an IBM-supplied JRE.

Edit the JTZU Settings file: runjtzuenv.bat on Windows or runjtzuenv.sh on other platforms.

In the JTZU Settings file, set JAVA_HOME to the path of the directory containing the JRE that you are going to use to run the utility.

Now that you have specified the JRE used to run the utility, you can carry out the following tasks:

1. Patch a JRE or SDK at a known location
2. Search for and locate JREs and SDKs
3. Search for and locate JREs and SDKs, patching everything it finds
4. Selectively search for JREs and SDKs, then perform a selective patching

How to patch a JRE or SDK at a known location

1. Set the value of NOGUI in the JTZU Settings file to false. The DISCOVERONLY setting is not used.
2. Run JTZU by executing runjtzu.bat on Windows platforms or runjtzu.sh on other platforms.
3. In response to the prompt, select Interactive mode and click Start.
4. Enter the location of the JRE in the text box or use the Browse button to select one.
5. Click Update to perform the time zone update for the selected JRE.

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

How to search for JREs and SDKs

1. Set the value of NOGUI in the JTZU Settings file to true.
2. Set the value of DISCOVERONLY to true.
3. Ensure that the DirectorySearch.txt file contains the value "all" as the only record. This is important on z/OS as the file can be corrupted.
4. Run JTZU by executing runjtzu.bat on Windows platforms or runjtzu.sh on other platforms

By default, JTZU will search the entire file system.

The utility will search for JREs and save the results in the SDKList.txt file. This operation can take a long time depending on the size of the system being searched, but your JREs can still be running while they are being discovered.

How to search for JREs and SDKs, patching every possible instance discovered

Use the GUI to locate and patch all JREs and SDKs on a system.

1. Set the value of NOGUI in the JTZU Settings file to false. The DISCOVERONLY setting is not used. The JREs and SDKs discovered are always patched if the time zone data is at an earlier level.
2. Run JTZU by executing runjtzu.bat on Windows platforms or runjtzu.sh on other platforms.
3. In response to the prompt, select Non-interactive mode and click Start. Progress will be displayed in a new window.

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

How to selectively search for SDKs and JREs and then perform selective patching

Two "advanced user" facilities are available. The first provides more control over directory searching and the second gives you more control of which SDKs and JREs to patch after a directory search. Each of these facilities can be used independently or they can be used together. You can limit the scope of directory searching to reduce the length of time this operation takes to run, which will depend on the size of the system being searched. Your JREs can still be running while they are being discovered.

Selective searching

You can perform a full search or a selective search of your directories, controlled by the DirectorySearch.txt file.

• To perform a full search, ensure that the DirectorySearch.txt file contains a single record with the word "all" (the supplied default).
• To perform a selective search, edit the DirectorySearch.txt file as described in "Selecting directories to search" below.
• Set the value of NOGUI in the JTZU Settings file to true.
• Run JTZU by executing runjtzu.bat on Windows platforms or runjtzu.sh on other platforms.

The SDKList.txt file will be populated with all the discovered SDKs and JREs along with the version of the time zone data they contain. For 1.2.2 and 1.3.1 SDKs and JREs that have not previously been patched by the JTZU utility, the time zone data level will be unknown.

Caution: On z/OS, the DirectorySearch.txt file shipped with the utility might be corrupt. If it is corrupt, replace the contents of the file with:

all
-/proc

Selective patching

1. Edit the SDKList.txt file, reducing the list to leave entries for the JREs selected for patching.
2. In the JTZU Settings file, set NOGUI to true and DISCOVERONLY to false.
3. Stop the JREs that are going to be patched.
4. Run JTZU by executing runjtzu.bat on Windows platforms or runjtzu.sh on other platforms.
5. Restart your JREs.

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

Selecting directories to search

Adding and removing directories

You can add and remove locations from the search by adding a directory to the DirectorySearch.txt file with a + or - at the beginning. There must not be a space between the + or - and the name of the directory.

On Windows, a DirectorySearch.txt file containing:

+c:\program files
-c:\program files\ibm\java142

will cause JTZU to recursively search the contents of the c:\program files directory, excluding c:\program files\ibm\java142.

On other platforms, a DirectorySearch.txt file containing:

+/usr
-/usr/bin

will cause the JTZU to recursively search the contents of the /usr directory, excluding /usr/bin.

The all keyword

If the all entry is the first entry in the file, then JTZU will search 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, then JTZU will search only in specified locations.

On Windows, a DirectorySearch.txt file containing:

all
-c:\windows

will cause JTZU to search the entire system except the c:\windows directory.

On other platforms, a DirectorySearch.txt file containing:

all
-/proc

will cause JTZU to search the entire system except the /proc directory. This is the default on non-Windows platforms.

Directories to exclude on non-Windows platforms

By default, JTZU will not search the /proc directory. This directory is excluded because it contains dynamically generated directories that could form an infinite loop.

You might also consider excluding the /dev and /sys directories depending on your platform. The /etc, /tmp, and /var directories are also unlikely to contain JREs.

Logging

Log information is written to the LogFile.log file. The log file shows all search paths, all detected JREs, and all patched JREs. Any errors are logged to this file.

Reverting changes for a JRE

• For 1.4 and 5.0 on AIX, Linux, Windows, and z/OS:
  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.
• For 1.2.2 and 1.3.1 on AIX, Linux, Windows, and z/OS:
  1. Ensure that the jre/lib/rt.jar_jtzubackup file exists.
  2. Delete the jre/lib/rt.jar file.
  3. Rename the jre/lib/rt.jar_jtzubackup file to jre/lib/rt.jar.
• On HP-UX and Solaris, delete the zi folder that is patched by the utility in the jre/lib folder of a Java installation and rename zi_jtzubackup as zi.
  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

1. Updating Java 1.2.2 SDKs/JREs

When updating Java 1.2.2 installations, in order to run JTZU, you must have an instance of Java 1.3.1 or later on the server being patched or run JTZU on a machine with network drives (mount points) to the server that need to be patched.

2. Patching the same JRE used to run the Utility

On AIX, Linux, Windows, and z/OS, attempting to patch the JRE used to run the Utility twice will result 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.<init>(JTZUVersionCheck.java:43)
        at JTZUUpdater.updateTimeZoneInformation(JTZUUpdater.java:65)
        at JTZUInteractive$JTZUInteractiveWorkerThread.updateTimeZoneInformation(
        JTZUInteractive.java:322)
        at JTZUInteractive$JTZUInteractiveWorkerThread.run(JTZUInteractive.java:186)

This error message can be avoided by restarting JTZU after patching the JRE for the first time.

On AIX, Linux, Windows, and z/OS, using a 1.3.1 JRE prior to SR10, attempting to patch the JRE used to run JTZU will result in the following error message:

java.lang.NoClassDefFoundError: javax/swing/JComponent$1
        at javax.swing.JComponent.revalidate(JComponent.java:3658)
        at javax.swing.AbstractButton.setMargin(AbstractButton.java:329)
        at javax.swing.plaf.basic.BasicOptionPaneUI.addButtonComponents(BasicOpt
        ionPaneUI.java:654)
        at javax.swing.plaf.basic.BasicOptionPaneUI.createButtonArea(BasicOption
        PaneUI.java:567)
        at javax.swing.plaf.basic.BasicOptionPaneUI.installComponents(BasicOptio
        nPaneUI.java:141)
        at javax.swing.plaf.basic.BasicOptionPaneUI.installUI(BasicOptionPaneUI.
        java:103)
        at javax.swing.JComponent.setUI(JComponent.java:346)

The JRE will still be successfully updated. This problem is fixed in 1.3.1 SR10.

3. JREs might be flagged as corrupt after patching

If you patch a JRE that has been installed under SMP/E on z/OS or installp on AIX, those utilities might flag the JRE as corrupt or inconsistent. Such a message is expected because you have modified the JRE.

JTZU reference information

JTZU settings

Settings are stored in a file named runjtzuenv.bat on Windows or runjtzuenv.sh on other platforms.

JAVA_HOME

Location of the JRE you will use to run the Utility. This must be a JRE, or the JRE contained within an SDK.

NOGUI

When set to true, JTZU will run in command-line mode only. The default is false, which sets JTZU to run with the graphical interface.

DISCOVERONLY

When set to true, JTZU only discovers IBM JREs and stores their locations in the SDKList.txt file. When set to false, JTZU only patches IBM JREs in the SDKList.txt file. The default is true.

FAQs

A set of FAQs covering JTZU is available here: http://www-1.ibm.com/support/docview.wss?rs=3068&context=SSNVBF&q1=time+zone+faq&uid=swg21249759&loc=en_US&cs=utf-8&lang=en