Upgrading the Oracle Tuxedo System to 10g Release 3 (10.3)

The following sections provide procedures for upgrading your Oracle Tuxedo or Oracle WebLogic Enterprise application to Oracle Tuxedo 10g Release 3 (10.3) using simple and hot upgrade procedures:

Preparing Your Machine for an Upgrade

Before you install the Oracle Tuxedo 10g Release 3 (10.3) software on a machine, make sure that the required version of the operating system and the compiler have been installed. For operating system and compiler requirements for each supported platform, see Oracle Tuxedo 10g Release 3 (10.3) Platform Data Sheets.

Selecting an Upgrade Procedure

If you are installing Oracle Tuxedo 10g Release 3 (10.3) on a platform that contains an earlier release of Oracle Tuxedo software or the Oracle WebLogic Enterprise software, be sure to read the following procedures carefully.

If you can shut down your application for the upgrade, then shut down your application and perform a simple upgrade. For instructions on performing a simple upgrade, see Performing a Simple Upgrade.

If you cannot shut down your application for the upgrade, you can perform a hot upgrade for any of the following software products to Oracle Tuxedo 10g Release 3 (10.3) without having to shut down your enterprise:

You can add the Oracle Tuxedo 10g Release 3 (10.3) software to existing Oracle Tuxedo or Oracle WebLogic Enterprise domains without shutting down the existing applications, and you can add new Oracle Tuxedo 10g Release 3 (10.3) application servers to those domains without shutting down the existing applications. For instructions on performing a hot upgrade, see Performing a Hot Upgrade.

Backing Up Files

There are certain files that you need to back up prior to the installation and then restore after the installation is complete. Any modifications that you made to these files will be overwritten when the new Oracle Tuxedo software is installed.

Back up the RM file to a temporary location. The RM file contains database vendor-specific settings that are used by commands such as buildtms and buildXAJS. It is located in the tux_prod_dir/udataobj directory, where tux_prod_dir is the directory in which you installed the Oracle Tuxedo or Oracle WebLogic Enterprise software.
Back up the tuxwsvr.ini and webgui.ini files to a temporary location. These files contain customized initialization settings for the Oracle Tuxedo Administration Console server and GUI. The tuxwsvr.ini file is located in the tux_prod_dir/udataobj directory, and the webgui.ini file is located in the tux_prod_dir/udataobj/webgui directory.
Back up the CATNAMES, jrepository, and jrly.config files. The CATNAMES file is located in the tux_prod_dir/locale directory. The jrepository and jrly.config files are located in the tux_prod_dir/udataobj/jolt directory structure.
Move any files that you or your coworkers added to the tux_prod_dir directory to a temporary location.
After the installation is complete, restore these files to their original locations.

Performing a Simple Upgrade

Shut down the application.
Back up files as described in Backing Up Files.
Update the text version of the configuration file on the MASTER machine by running the tmunloadcf(1) command.
Back up the old binary version of the configuration file.
If upgrading a Oracle Tuxedo 9.1 machine, uninstall the Oracle Tuxedo system software as described in Uninstalling Oracle Tuxedo.
If upgrading a Windows machine running Oracle WebLogic Enterprise or Oracle Tuxedo 10.0 or earlier software, perform the additional steps specified in Performing Additional Upgrade Steps to Windows 2003 Server.
Install the Oracle Tuxedo 10g Release 3 (10.3) software on at least the MASTER and backup MASTER machines.
Reload the text version of the configuration file by running tmloadcf(1) on the MASTER machine.
Recompile and relink your application programs.
Reboot the application.
As time permits, shut down and upgrade the other machines in your configuration.

Performing Additional Upgrade Steps to Windows 2003 Server

For a Windows 2003 machine running Oracle WebLogic Enterprise or Oracle Tuxedo 10g Release 3 (10.3) or earlier software, perform the following additional steps before installing the Oracle Tuxedo 10g Release 3 (10.3) software to ensure that you are starting with a clean system.

Stop the Tuxedo TListen and Oracle procMGR services. From the Start menu, click Start All Programs Administrative Tools Services. The Services window appears.

Note:

The Tuxedo Oracle procMGR service is called IPC Helper in Oracle Tuxedo 6.5 or Oracle WebLogic Enterprise 5.1.

Scroll to the entry for the TListen service, select it, and then click the Stop button. The Status value should change from Started to a blank entry. Then scroll to the Oracle procMGR (or IPC Helper) service, select it, and click the Stop button. In some cases, you may see an error; however, the service’s Status value should change from Started to a blank entry. Click the Close button.
Run the Windows Add/Remove program to remove the prior Oracle Tuxedo or Oracle WebLogic Enterprise software version. From the Start menu, choose Start Settings Control Panel Add/Remove Programs. The Add/Remove Programs Properties window appears.
Scroll to the entry for the prior Oracle Tuxedo or Oracle WebLogic Enterprise software, select it, and click the Add/Remove button.

Note:

If you have both the C++ and Java components of WebLogic Enterprise 5.1 installed on your machine, you must remove the Java software before removing the C++ software.

In response to the prompt, confirm that you want to uninstall the software. After the program finishes, the Remove Programs From Your Computer window appears.
If the uninstall program was not able to remove all directories (usually because the files were added after the original installation), you can click the Details button to find out which directories remain on your system. If the files in the directories contain changes that you made, such as a modified sample file, move the modified files to a temporary location.
Reboot your system after the uninstall completes.

Upgrading from Tuxedo 6.5 to Tuxedo 10g Release 3 (10.3)

If you are upgrading from Tuxedo 6.5 to Tuxedo 10g Release 3 (10.3), please note the following:

In order to allow a Tuxedo 10g Release 3 (10.3) server to interoperate with Tuxedo 6.5 software, the Tuxedo 10g Release 3 (10.3) server servopts -t option must be specified. The server may be a workstation listener (WSL) process (where the servopts -t option allows interoperability for all of its workstation handler—WSH—processes), a domain gateway (GWTDOMAIN) process, or a system or application server process. For more information, seeGWTDOMAIN(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, And System Processes Reference.
In order to allow a domain gateway (GWTDOMAIN) in Tuxedo 10g Release 3 (10.3) to interoperate with a domain gateway running on Tuxedo 6.5. you must upgrade to Tuxedo 6.5 patch level 446.

If you have not upgraded to patch level 446, then you must set the TM_GWT_OLDSECCHECK environment variable of the domain gateway in this Tuxedo 10g Release 3 (10.3). For more Oracle Tuxedo environment variable information, see tuxenv(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, And System Processes Reference.

If your Tuxedo 6.5 COBOL program calls TPINITIALIZE(), you must set the TM_CBL_IGNORE_CONTEXT environment variable to “Y” when you run the COBOL application. For more Oracle Tuxedo environment variable information, see tuxenv(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, And System Processes Reference.

Performing a Hot Upgrade

Before performing a hot upgrade, back up files as described in Backing Up Files.

During the hot upgrade, you must shut down the MASTER and backup MASTER machines serially. The remainder of the configuration is unaffected.

Pre-Upgrade Notes

Once you have finished migrating the MASTER to Oracle Tuxedo 10g Release 3 (10.3) (via a hot upgrade), you will not be able to migrate it back to the acting backup until you have upgraded the backup to Oracle Tuxedo 10g Release 3 (10.3). In other words, migrating the MASTER is an irreversible procedure; once you have completed it, you cannot change the MASTER back to the release of the Oracle Tuxedo software on which it was running previously.

When you run tmadmin(1) on a Oracle Tuxedo 10g Release 3 (10.3) machine with an old-release MASTER, the UPGRADE file shown in Hot-Upgrade Example must reside in the current directory. To make sure that the files are in the current directory, you might, for example, run tmadmin from the Tuxedo application directory: %APPDIR% (Windows)/ $APPDIR (UNIX) directory.

During migration, keep in mind the following guidelines regarding the Oracle Tuxedo data storage areas:

To minimize downtime, Oracle recommends installing Oracle Tuxedo 10g Release 3 (10.3) on the MASTER machine and backup MASTER, and rebuilding all clients and servers in the directory on each machine that is defined by %APPDIR%/ $APPDIR, in parallel with the directory in which the old-release clients and servers were created. In other words, both an old-release application and a Oracle Tuxedo 10g Release 3 (10.3) application should be available on each machine. This advice is not a requirement, but a recommendation.

The Oracle Tuxedo software supports device list path entries of up to 256 bytes in length (in previous releases the limit was 64 bytes in length.) Queue Spaces, TLOG files, and other configuration files originally created with an earlier version of Oracle Tuxedo are understood and supported with this release. However, such device lists originally created with Oracle Tuxedo 8.0 or earlier are restricted to 64-byte path names. Therefore, if the administrator wants to add a new extent using a path name greater than 64 bytes in length to a queue space in the future and such queue space is empty when the upgrade is performed, the administrator may want to create the queue space device list and the queue space at the time of the hot upgrade. Many applications need to preserve queue spaces across an upgrade and will not be able to recreate them. Furthermore, most applications will not need to add queue space extent in the future or will be able to do so using path names no longer than the ones they are currently using. This queue space recreation is completely optional and mentioned for completeness.

Hot-Upgrade Procedure

Make sure your environment is set up as follows:

The configuration must have a backup MASTER machine.
The MODEL option in the configuration must be set to MP.
The MIGRATE option in the configuration must be set.

If upgrading a Oracle Tuxedo 9.1 machine, uninstall the Oracle Tuxedo system software as specified in Uninstalling Oracle Tuxedo.
If upgrading a Windows 2003 machine running Oracle WebLogic Enterprise or Oracle Tuxedo 9.1 or earlier software, perform the additional steps specified in Performing Additional Upgrade Steps to Windows 2003 Server.
Shut down the backup MASTER machine.
Install the Oracle Tuxedo 10g Release 3 (10.3) software on the backup MASTER machine and reboot the backup machine.
Migrate the MASTER machine running the old release to the backup MASTER machine running Oracle Tuxedo10g Release 3 (10.3).
Shut down the machine that is now acting as the backup MASTER.
Install Oracle Tuxedo 10g Release 3 (10.3) on the old MASTER.
Using Oracle Tuxedo 10g Release 3 (10.3), reboot the machine that you shut down in step 7.

For more information about hot upgrades, refer to the following section, Hot-Upgrade Example.

Hot-Upgrade Example

The following example describes a sample scenario for a hot upgrade and the sequence of steps to perform the hot upgrade.

A machine called MACH1 that is configured as the MASTER and that runs an old release

A corresponding application directory called $APPDIR1
A corresponding configuration file called $TUXCONFIG1

A machine called MACH2 that is configured as the backup

A corresponding application directory called $APPDIR2
A corresponding configuration file called $TUXCONFIG2

Refer to the following instruction sequence to perform a hot upgrade for your application.

MACH1> tmshutdown -B MACH2 -l MACH2
MACH1> Run tmconfig to reset the APPDIR, TUXCONFIG, TUXDIR for MACH2
       MACH2> Kill tlisten process
       MACH2> Load Tuxedo 10gR3 if it is not already loaded
       MACH2> cd $APPDIR2
       MACH2> rm $TUXCONFIG2
       MACH2> >UPGRADE    # Indicator that upgrade being done
       MACH2> Reset PATH, LD_LIBRARY_PATH, TUXCONFIG, APPDIR
       MACH2> Rebuild clients and servers, create TLOG
       MACH2> Start Tuxedo 10gR3 tlisten
MACH1> >UPGRADE    # Indicator that upgrade being done
MACH1> tmboot -B MACH2 -l MACH2
       MACH2> tmadmin
              master
              y
              psr
              q
       MACH2> tmshutdown -B MACH1 -l MACH1
       MACH2> Run tmconfig to reset the APPDIR, TUXCONFIG, TUXDIR for MACH1
MACH1> Kill tlisten process
MACH1> Load Tuxedo 10gR3 if it is not already loaded
MACH1> cd $APPDIR1
MACH1> rm $TUXCONFIG1
MACH1> Reset PATH, LD_LIBRARY_PATH, TUXCONFIG, APPDIR
MACH1> Rebuild clients and servers, create TLOG
MACH1> Start Tuxedo 10gR3 tlisten
MACH1> rm UPGRADE  # Remove indicator that upgrade being done
       MACH2> rm UPGRADE  # Remove indicator that upgrade being done
       MACH2> tmboot -B MACH1 -l MACH1

Rebuilding an Application

Now that you have successfully installed the Oracle Tuxedo software, you need to rebuild all application clients and servers that you want to execute on a system upgraded to Oracle Tuxedo 10g Release 3 (10.3). You should also remove any old TUXCONFIG files and reload them using the newly installed tmloadcf(1).

If your Oracle Tuxedo system applications are distributed, the MASTER and backup MASTER machines must run the highest release of the Oracle Tuxedo software of any machines in the configuration. Other machines, including Workstation clients, may continue to use executables from an earlier release. For example, even if your MASTER and backup MASTER machines are running Oracle Tuxedo 10g Release 3 (10.3), Oracle Tuxedo 6.5 or later may still be used on other machines.

There is one important exception to the “highest release” rule. If you wish to install Oracle Tuxedo 10g Release 3 (10.3) only on Workstation clients, and you do not want to upgrade any of your Oracle Tuxedo system server machines to Oracle Tuxedo 10g Release 3 (10.3), you may do so. In other words, with any release level beginning with Oracle Tuxedo 6.5, Workstation clients may be intermixed freely in a configuration in which the MASTER machines is running Oracle Tuxedo 6.5 or later.

Installing Oracle Jolt 10g Release 3 (10.3) with Oracle WebLogic Server

This section provides supplementary installation instructions for customers using Oracle Jolt 10g Release 3 (10.3) with Oracle WebLogic Server 6.1, 7.0, or 8.1 and Oracle Tuxedo 6.5, 7.1, 8.0, 8.1, 9.0, 9.1, or 10.0. You can install the Jolt client personality software known as “Oracle Jolt for Oracle WebLogic Server” on an Oracle WebLogic Server 6.1, 7.0, or 8.1 machine by copying the Jolt client personality software from a Oracle Tuxedo 10g Release 3 (10.3) machine to the target Oracle WebLogic Server machine. Of course, if the Oracle Tuxedo 10g Release 3 (10.3) machine and the target Oracle WebLogic Server machine are the same machine, you need only include the Jolt client library class files in your CLASSPATH variable setting.

The “Oracle Jolt for Oracle WebLogic Server” client software consists of three JAR files: jolt.jar, joltjse.jar, and joltwls.jar. Include these files in your CLASSPATH variable setting.

Installing the Oracle Tuxedo System