Upgrading the BEA Tuxedo System to Release 8.0

 

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

• Preparing Your Machine for an Upgrade

• Selecting an Upgrade Procedure

• Backing Up Files

• Performing a Simple Upgrade

• Additional Upgrade Requirements for Windows 2000

• Performing a Hot Upgrade

• Upgrading BEA Jolt to Release 8.0

• Rebuilding an Application

 

---

Preparing Your Machine for an Upgrade

Before you install the BEA Tuxedo 8.0 software on a machine, make sure that the required version of the operating system and the compiler have been installed.

Note: Installing the operating system and compiler may take a significant amount of time.

For operating system and compiler requirements for each supported platform, see BEA Tuxedo 8.0 Platform Data Sheets.

 

---

Selecting an Upgrade Procedure

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

 

If you can shut down your application for the upgrade to BEA Tuxedo 8.0, we recommend a simple upgrade. For a simple upgrade on a Windows 2000 system, start by removing the existing BEA WebLogic Enterprise or BEA Tuxedo software by using the Windows Add/Remove (uninstall) program, and then install BEA Tuxedo 8.0. For instructions, see Performing a Simple Upgrade.

If you cannot shut down your application for the upgrade to BEA Tuxedo 8.0, you can perform a hot upgrade, instead, from any of the following products:

• Versions 4.2, 5.0.1, or 5.1 of BEA WebLogic Enterprise

• Versions 6.3, 6.4, 6.5, or 7.1 of BEA Tuxedo

The hot upgrade process allows you to add the BEA Tuxedo 8.0 software to existing BEA WebLogic Enterprise or BEA Tuxedo domains without first shutting down those domains. It also enables you to add new BEA Tuxedo 8.0 applications to those domains without shutting down the existing applications. For instructions on performing a hot upgrade, see Performing a Hot Upgrade.

 

---

Backing Up Files

Certain files on your system, such as RM and webgui.ini, are overwritten when the new BEA Tuxedo software is installed. As a result, any modifications you have made to these files are lost at that time. If you want to preserve your modifications to these files, you must make backup copies of the files before starting the installation process. Then you will be able to restore your versions once installation is complete.

To avoid losing your modifications, complete the following procedure:

1. 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 %TUXDIR%\udataobj or $TUXDIR/udataobj directory, where TUXDIR is the directory in which you installed the BEA WebLogic Enterprise or BEA Tuxedo software.

2. Back up the webgui.ini file to a temporary location. The webgui.ini file contains customized initialization settings for the BEA Tuxedo Administration Console. It is located in %TUXDIR%\udataobj\webgui or in the $TUXDIR/udataobj/webgui directory.

3. Move any files that you or your coworkers added to the %TUXDIR% directory to a temporary location.

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

1. Shut down the application.

2. Back up any files you want to preserve, as described in Backing Up Files.

3. Update the text version of the configuration file on the MASTER machine by running the tmunloadcf(1) command.

4. Back up the old binary version of the configuration file.

5. If you are upgrading the software on a Windows 2000 machine, perform the additional steps specified in Additional Upgrade Requirements for Windows 2000.

6. Install the BEA Tuxedo 8.0 software on at least the MASTER and backup machines.

7. Reload the text version of the configuration file by running tmloadcf(1) on the MASTER machine.

8. If necessary, recompile and relink your application programs.

9. Reboot the application.

10. As time permits, shut down and upgrade the other machines in your configuration.

 

---

Additional Upgrade Requirements for Windows 2000

For a Windows 2000 machine, to ensure that you are starting with a clean system, perform the following additional steps before installing the BEA Tuxedo 8.0 software.

1. Stop the TListen and Tuxedo IPC Helper services. From the Start menu, click Start—>Programs—>Administrative Services—>Services. The Services window appears.

   Note: The Tuxedo IPC Helper service is called BEA procMGR in BEA Tuxedo 8.0.

2. 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 Tuxedo 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.

3. Run the Windows Add/Remove program to remove the prior BEA WebLogic Enterprise or BEA Tuxedo software version. From the Start menu, choose Start—>Settings—>Control Panel—>Add/Remove Programs. The Add/Remove Programs Properties window is displayed.

4. Scroll to the entry for the prior BEA WebLogic Enterprise or BEA Tuxedo software, select it, and click the Add/Remove button.

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

5. In response to the prompt, confirm that you want to uninstall the software. After the program finishes, the Remove Programs From Your Computer window is displayed.

6. 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 those directories contain changes that you made, such as a modified sample file, move them to a temporary location.

7. If the prior version was WebLogic Enterprise 4.2, you may need to uninstall the WebLogic Enterprise Java and WebLogic Enterprise C++ software in separate steps. Remember: if you have both the C++ and Java components of WebLogic Enterprise 4.2 installed on your machine, you must remove the Java software before removing the C++ software, as shown in step 5.

8. Reboot your system after the uninstall process is completed.

 

---

Performing a Hot Upgrade

Before performing a hot upgrade, back up any files that you need to save, as described in Backing Up Files.

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

Pre-Upgrade Notes

Once you have finished migrating the MASTER to BEA Tuxedo 8.0 (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 8.0. 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 8.0 machine with an old-release MASTER, the UPGRADE file (as shown in the section 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 APPDIR.

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 BDMCONFIG file, leave it as is.

To minimize downtime, we recommend installing BEA Tuxedo 8.0 on the MASTER and backup, and rebuilding all clients and servers in the directory on each machine that is defined by 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 8.0 application should be available on each machine.) This is not a requirement, but a recommendation.

When migrating from an old release, you must rebuild your clients and servers. Additionally, you must always rebuild whenever you reinstall the BEA Tuxedo software on HP-UX. Note that the HP-UX shared library loader does not, by default, use the paths specified in the SHLIB_PATH environment variable when trying to locate the shared libraries needed by an executable at run time. To enable the SHLIB_PATH lookup, the "W1, +s" compilation option must be passed to either the C or C++ compiler. (This procedure is not necessary on any other platform supported by the BEA Tuxedo system.) That is, your application programs must be recompiled with the following setting:

CFLAGS=Wl,+s

This setting causes the compiler to pass the +s option to the link editor when the application is recompiled. It changes the program's default behavior during future upgrades.

Note: The buildserver, buildobjserver, buildclient, and buildobjclient commands include the +s option of the link editor; you do not need to specify +s explicitly. If you are using a different build procedure, however, you must specify the +s option.

Hot-Upgrade Procedure

1. Make sure your environment is set up as follows:

   • The configuration must have a backup machine.

   • The MODEL option must be set to MP.

   • The MIGRATE option must be set.

2. If you are upgrading a Windows 2000 machine, perform the additional steps specified in Additional Upgrade Requirements for Windows 2000.

3. Shut down the backup machine.

4. Install the BEA Tuxedo 8.0 software on the backup machine and reboot the backup machine.

5. Migrate the MASTER running the old release to the backup running BEA Tuxedo 8.0.

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

7. Using BEA Tuxedo 8.0, reboot the machine that you shut down in step 6.

Hot-Upgrade Example

Suppose you have the following two machines 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.

MACH1> tmshutdown -B MACH2 -l MACH2
 
MACH1> Run tmconfig to reset the APPDIR, TUXCONFIG, TUXDIR for MACH2
 
       MACH2> Kill tlisten process
 
       MACH2> Load System 8.0 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 System 8.0 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 System 8.0 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 System 8.0 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 on a Windows 2000 platform, be sure to stop the BEA Tuxedo IPC Helper (called BEA procMGR in BEA Tuxedo 8.0) service after stopping the tlisten process and to start the BEA procMGR service before starting the tlisten process.

 

---

Upgrading BEA Jolt to Release 8.0

BEA Jolt 8.0 interoperates with BEA Tuxedo 8.0, but Release 1.2.1 and earlier releases of BEA Jolt do not. Therefore, if you are planning to run BEA Jolt with BEA Tuxedo 8.0, you must install BEA Jolt 8.0.

If you have an earlier release of Jolt installed, you must uninstall it and then install Release 8.0; you cannot upgrade directly from an earlier release of BEA Jolt.

 

---

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 8.0. 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, then the MASTER and backup MASTER nodes must run the highest release of the BEA Tuxedo software of any nodes in the configuration. Other nodes, including Workstation clients, may continue to use executables from an earlier release. For example, even if your MASTER and backup MASTER are running BEA Tuxedo 8.0, BEA Tuxedo 6.3 or later may still be used on other machines.

There is one important exception to the highest release rule. If you want to install BEA Tuxedo 8.0 only on Workstation clients, and you do not want to upgrade any of your BEA Tuxedo system server machines to BEA Tuxedo 8.0, you may do so. In other words, with any release level beginning with 6.3, Workstation clients may be intermixed freely in a configuration in which the MASTER is running release 6.3 or later.