Installing the Tuxedo System

Upgrading the BEA Tuxedo System to Release 9.1

The following sections provide procedures for upgrading your BEA Tuxedo or BEA WebLogic Enterprise application to BEA Tuxedo 9.1 using simple and hot upgrade procedures:

Preparing Your Machine for an Upgrade

Before you install the BEA Tuxedo 9.1 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 BEA Tuxedo 9.1 Platform Data Sheets.

Selecting an Upgrade Procedure

If you are installing BEA Tuxedo 9.1 on a platform that contains an earlier release of BEA Tuxedo software or the BEA WebLogic Enterprise software, be sure to read the following procedures carefully.

insup.htm

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 BEA Tuxedo 9.1 without having to shut down your enterprise:

Versions 6.5, 7.1, 8.0, 8.1, or 9.0 of BEA Tuxedo
Version 5.1 of WebLogic Enterprise

You can add the BEA Tuxedo 9.1 software to existing BEA Tuxedo or BEA WebLogic Enterprise domains without shutting down the existing applications, and you can add new BEA Tuxedo 9.1 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 BEA Tuxedo software is installed.

To avoid having to modify these files again, follow these steps:

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 BEA Tuxedo or BEA WebLogic Enterprise software.

Back up the tuxwsvr.ini and webgui.ini files to a temporary location. These files contain customized initialization settings for the BEA 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

A simple upgrade consists of the following basic steps:

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 BEA Tuxedo 9.0 machine, uninstall the BEA Tuxedo system software as described in Uninstalling BEA Tuxedo.

If upgrading a Windows machine running BEA WebLogic Enterprise or BEA Tuxedo 9.0 or earlier software, perform the additional steps specified in Performing Additional Upgrade Steps to Windows 2003 Server.

Install the BEA Tuxedo 9.1 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.

If necessary, 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 BEA WebLogic Enterprise or BEA Tuxedo 9.0 or earlier software, perform the following additional steps before installing the BEA Tuxedo 9.1 software to ensure that you are starting with a clean system.

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

Note: The Tuxedo BEA procMGR service is called IPC Helper in BEA Tuxedo 6.5 or BEA 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 BEA 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 BEA Tuxedo or BEA 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 BEA Tuxedo or BEA 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.

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 for Tuxedo 9.0 Users

Tuxedo 9.1 is a minor upgrade release for Tuxedo 9.0 and is 100% compatible with Tuxedo 9.0. You can think of Tuxedo 9.0 and Tuxedo 9.1 as being the same when performing an upgrade. Upgrading constraints applied to Tuxedo 8.1 or earlier release users may not apply to Tuxedo 9.0 users, note the following:

Non-master node running Tuxedo 9.1 can coexist with master node running Tuxedo 9.0 in an MP configuration. This means migrating to Tuxedo 9.1 is reversible for Tuxedo 9.0 users, although this is not recommended.
A Tuxedo 9.0 application can run directly on top of Tuxedo 9.1 installation without rebuilding the application clients and servers.
If you install Tuxedo 9.1 in the original Tuxedo 9.0 directory, TUXDIR remains the same after upgrading. You do not need to reload the configuration (TUXCONFIG) file.

Note: Tuxedo 9.0 users can use the general Hot-Upgrade Example, or the Tuxedo 9.0-Tuxedo 9.1 Hot-Upgrade Examples.

Pre-Upgrade Notes for Tuxedo 8.1 or Earlier Release Users

Once you have finished migrating the MASTER to BEA Tuxedo 9.1 (via a hot upgrade), you will not be able to migrate it back to the acting backup until you have upgraded the backup to BEA Tuxedo 9.1. 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 BEA Tuxedo software on which it was running previously.

When you run tmadmin(1) on a BEA Tuxedo 9.1 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 BEA Tuxedo data storage areas:

You will be instructed to remove the old TUXCONFIG file. The TUXCONFIG file is propagated automatically when the backup machine is run; therefore, you do not need to do anything.
Create the TLOG when you load the software. If you already have a TLOG, remove it.
Do not do anything with application queue spaces and queues.
If you have a Domains configuration (BDMCONFIG) file, leave it as is.

To minimize downtime, BEA recommends installing BEA Tuxedo 9.1 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 BEA Tuxedo 9.1 application should be available on each machine. This advice is not a requirement, but a recommendation.

The BEA 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 BEA Tuxedo are understood and supported with this release. However, such device lists originally created with BEA 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

This section provides an overview of the tasks for a "hot upgrade."

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 BEA Tuxedo 9.0 machine, uninstall the BEA Tuxedo system software as specified in Uninstalling BEA Tuxedo.

If upgrading a Windows 2003 machine running BEA WebLogic Enterprise or BEA Tuxedo 9.0 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 BEA Tuxedo 9.1 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 BEA Tuxedo9.1.

Shut down the machine that is now acting as the backup MASTER.

Install BEA Tuxedo 9.1 on the old MASTER.

Using BEA Tuxedo 9.1, 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.

Suppose you have the following on a UNIX platform:

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.

Listing 5-1 Typical Hot Upgrade

MACH1> tmshutdown -B MACH2 -l MACH2
MACH1> Run tmconfig to reset the APPDIR, TUXCONFIG, TUXDIR for MACH2
       MACH2> Kill tlisten process
       MACH2> Load Tuxedo 9.1 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 9.1 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 9.1 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 9.1 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

Note: If you are performing the upgrade illustrated in the previous example from a Windows platform, be sure to stop the Tuxedo BEA procMGR (called IPC Helper in BEA Tuxedo 6.5 or BEA WebLogic Enterprise 5.1) service after stopping the tlisten process and to start the BEA procMGR service before starting the tlisten process.

Tuxedo 9.0-Tuxedo 9.1 Hot-Upgrade Examples

The following example depicts a sample scenario for a Tuxedo 9.0 - Tuxedo 9.1 smooth upgrade and the sequence of steps to perform the hot upgrade.

Suppose you have the following on a UNIX platform:

A machine called MACH1 that is configured as the MASTER and that runs Tuxedo 9.0 release

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

A machine called MACH2 that is configured as the NON-MASTER and that also runs Tuxedo 9.0

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 and then continue your application.

Listing 5-2 Tuxedo 9.0 Non-Master to Tuxedo 9.1 Hot Upgrade

MACH1> tmshutdown -B MACH2 -l MACH2							 
       MACH2> Kill tlisten process
       MACH2> Install Tuxedo 9.1 on the same location as Tuxedo 9.0
       MACH2> Load System 9.1 if it is not already loaded
       MACH2> >cd $APPDIR2
       MACH2> Start System 9.1 tlisten
MACH1> tmboot -B MACH2 -l MACH2

If want to upgrade Tuxedo 9.0 Master machine to Tuxedo 9.1, refer to the following steps:

Listing 5-3 Tuxedo 9.0 Master to Tuxedo 9.1 Hot Upgrade

MACH1> tmshutdown -B MACH2 -l MACH2
MACH1> Run tmconfig to change MASTER from "Mater" to "Master,Slave" (backup module)
   MACH2> rm $TUXCONFIG2
MACH1> tmboot -B MACH2 -l MACH2
   MACH2> tmadmin
          master
          y
          psr
          q
   MACH2> tmshutdown -B MACH1 -l MACH1
MACH1> Kill tlisten process
MACH1> Install Tuxedo 9.1 on the same location as Tuxedo 9.0
MACH1> Load Tuxedo 9.1 if it is not already loaded
MACH1> cd $APPDIR1
MACH1> rm $TUXCONFIG1
MACH1> Start System 9.1 tlisten
   MACH2> tmboot -B MACH1 -l MACH1
MACH1> tmadmin
       master
       y
       psr
       q

Rebuilding an Application

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

If your BEA Tuxedo system applications are distributed, the MASTER and backup MASTER machines must run the highest release of the BEA 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 BEA Tuxedo 9.1, BEA 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 BEA Tuxedo 9.1 only on Workstation clients, and you do not want to upgrade any of your BEA Tuxedo system server machines to BEA Tuxedo 9.1, you may do so. In other words, with any release level beginning with BEA Tuxedo 6.5, Workstation clients may be intermixed freely in a configuration in which the MASTER machines is running BEA Tuxedo 6.5 or later.

Installing BEA Jolt 9.1 with BEA WebLogic Server

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

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

For instructions on configuring the Jolt connection pool on BEA WebLogic Server, see Using BEA Jolt with BEA WebLogic Server.