IBM Time Zone Update Utility for Java (JTZU)

Readme


Last updated 15 February 2007.

(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
Downloading and Installing JTZU
Running JTZU
Reverting changes for a JRE
Known limitations
JTZU reference information

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 by 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.7a contains timezone data at the level of Olson's tzdata2007a.

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 tzdata2007a, any JRE with a time zone data level of tzdata2006p or earlier will be updated.

SDKs and JREs detected and patched by JTZU

JTZU does not support Java on Series i (i5/OS) platforms. To update Java on i5/OS, refer to Updating Java for Daylight Time Saving changes on i5/OS platforms.

SDKs and JREs detected and patched by JTZU:

Note: * Java 1.2.2 and 1.3.0 are no longer supported releases. JTZU is able to process some 1.2.2 and 1.3.0 JREs and SDKs, but this ability has not been fully tested across all platforms. You may use JTZU on these releases, with the understanding that you do so at your own risk, and a response or fix to any problems that you report is not guaranteed. No assistance is possible with Java 1.2.2 or 1.3.0 on Solaris or HP-UX platforms, because these releases are no longer supported by Sun and HP.

SDKs and JREs detected but not patched by JTZU

The following SDKs and JREs will be detected by the JTZU tool during the discovery process, but can not be patched by JTZU.

For a complete list of the JREs and SDKs found on your system, see the LogFile.log file generated by JTZU.

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. Use the jar utility where available:
    jar -xvf <filename>
  4. On AIX, z/OS, Linux, Solaris, and HP-UX platforms, you need to set the executable bit for the utility. At a shell prompt, type:
    chmod 755 runjtzu.sh

Running JTZU

Prerequisites

Specifying the JRE used to run the Utility

Before running JTZU, you must decide which JRE to use to run it. This JRE 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 or 1.3.0 JRE or SDK, you must use a 1.3.1 (or higher level) JRE to drive the utility. If this JRE is not available on the local machine, it can be located on a network drive.

Edit the JTZU Settings file: runjtzuenv.bat on Windows, runjtzuenv.cmd on OS/2, 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.

On OS/2 platforms, set JTZU_HOME in the runjtzu.cmd file to the path of the directory containing the JTZU 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 JREs and SDKs
  3. Search for JREs and SDKs, patching supported releases
  4. Search for JREs and SDKs and then perform 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, runjtzu.cmd on OS/2 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 step is important on z/OS because the file can be corrupted.
  4. Run JTZU by executing runjtzu.bat on Windows platforms, runjtzu.cmd on OS/2 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 LogFile.log file. SDKs and JREs that can be updated by JTZU will also be stored 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 all JREs and SDKs on a system, then patch supported JREs and SDKs.

  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, runjtzu.cmd on OS/2 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.

The GUI will display all SDKs and JREs supported for patching in the top section, and all SDKs and JREs that require patching in the bottom section. The GUI will not display SDKs and JREs that JTZU cannot patch.

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 over the 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.

The SDKList.txt file will be populated with all the discovered SDKs and JREs that can be patched 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 JTZU, the time zone data level will be shown as "Update Required".

Complete or selective patching

You can patch all the instances discovered or you can select a subset of them to patch by editing the list of JREs found by running JTZU in discovery mode.
  1. For selective patching, edit the SDKList.txt file. Remove any entries that you do not want to patch.
  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, runjtzu.cmd on OS/2 platforms, or runjtzu.sh on other platforms.
  5. Restart your JREs.

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

Silent patching

You can patch all the instances supported for patching without any user interaction by running JTZU in SilentPatch mode.
  1. In the JTZU Settings file, set NOGUI to true, DISCOVERONLY to false, and SILENTPATCH to true.
  2. Stop the JREs that are going to be patched.
  3. Run JTZU by executing runjtzu.bat on Windows platforms, runjtzu.cmd on OS/2 platforms, and runjtzu.sh on other platforms.
  4. Restart your JREs.

Selecting directories to search

Directory searching is controlled by 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.

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 or OS/2, a DirectorySearch.txt file containing:

+c:\programs
-c:\programs\ibm\java142

will cause JTZU to recursively search the contents of the c:\programs directory, excluding c:\programs\ibm\java142 and all its subdirectories.

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

The all keyword

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

On Windows or OS/2, a DirectorySearch.txt file containing:

all
-c:\workarea

will cause JTZU to search the entire system except the c:\workarea 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 AIX, z/OS, Linux, Solaris, and HP-UX platforms.

Directories to exclude on AIX, z/OS, Linux, Solaris, and HP-UX 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

On AIX, Linux, Windows, and z/OS, the JTZU makes a backup of the core.jar file as core.jar_jtzubackup (rt.jar as rt.jar_jtzubackup on 1.3.1 and older) under the jre/lib folder of the Java installation. On HP-UX and Solaris, the JTZU makes a backup of the zi directory as zi_jtzubackup under the jre/lib folder of the JRE installation.

Known limitations

The following Web site contains information about known problems with DST adjustment that apply whether you have run JTZU to upgrade your system or upgraded using service refreshes or fix packs:

http://www-1.ibm.com/support/docview.wss?rs=3068&context=SSNVBF&uid=swg21250503

In addition, the following limitations apply to JTZU:

1. Updating Java 1.2.2 SDKs and JREs

When updating Java 1.2.2 SDKs and JREs, you must have an instance of Java 1.3.1 or later on the server being patched or you must 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 patches IBM JREs in the SDKList.txt file. The default is true.
SILENTPATCH
When set to true, JTZU patches the SDKs and JREs without any user interaction in command-line 'Patch' mode.

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