5 Upgrading the Oracle Tuxedo System to Tuxedo 22c Release 1(22.1.0.0.0)

The following sections provide procedures for upgrading your Oracle Tuxedo 12c Release 2 (12.2.2) to Oracle Tuxedo 22c using simple and hot upgrade procedures:

5.1 Upgrade Paths

The following figure illustrates the existing Oracle Tuxedo products that can be upgraded to Oracle Tuxedo 22c Release 1 (22.1.0.0.0):

Figure 5-1 Upgrade Paths


Upgrade Paths Diagram

When you shut down the domain (application) targeted for the upgrade, you must shut down the domain and perform a simple upgrade. If you cannot shut down the domain targeted for the upgrade, perform a hot upgrade, that is, add the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) system software to the existing Oracle Tuxedo domain without shutting down the domain.

5.2 Preparing Your Machine for an Upgrade

Before you install the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) 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 22c Release Platform Data Sheets.

5.3 Selecting an Upgrade Procedure

If you are installing Oracle Tuxedo 22c Release 1 (22.1.0.0.0) on a platform that contains an earlier release of Oracle Tuxedo software, then make sure you read the following procedures carefully.

Oracle Tuxedo Upgrade Procedures

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 22c Release 1 (22.1.0.0.0) without having to shut down your application:
  • Versions 12.1.1.0.0, 12.1.3.0.0, and 12.2.2.0.0 of Oracle Tuxedo

You can add the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) software to existing Oracle Tuxedo domains without shutting down the existing applications, and you can also add new Oracle Tuxedo 22c Release 1 (22.1.0.0.0) application servers to those domains without shutting down the existing applications. For instructions on performing a hot upgrade, see Performing a Hot Upgrade.

5.4 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 are overwritten when the new Oracle Tuxedo software is installed.

Follow these steps to avoid having to modify these files again:

  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 tux_prod_dir/udataobj directory, where tux_prod_dir is the directory in which you installed the Oracle Tuxedo.
  2. Back up the CATNAMES, jrepository, and jrly.config files. The CATNAMES file is located in the tux_prod_dir/localedirectory. The jrepository file is located in the tux_prod_dir/udataobj/jolt/repository/ directory structure and the jrly.config file is located in the tux_prod_dir/udataobj/jolt/relay/ directory structure.
  3. Move any files that you added to the tux_prod_dir directory to a temporary location.
  4. After the installation is complete, restore these files to their original locations.

5.5 Performing a Simple Upgrade

A simple upgrade consists of the following basic steps:

  1. If you already have the DMTLOG and TLOG, ensure that there are no pending transaction logs in these files.
  2. Shut down the application.
  3. Back up files as described in Backing Up Files.
  4. Update the text version of the configuration file on the MASTER machine by running the tmunloadcf(1)command.
  5. Back up the old binary version of the configuration file.
  6. If upgrading an Oracle Tuxedo 9.1 machine, uninstall the Oracle Tuxedo system software as described in Uninstalling Oracle Tuxedo.
  7. Install the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) software on at least the MASTER and backup MASTER machines.
  8. Reload the text version of the configuration file by running tmloadcf(1) on the MASTER machine.
  9. Recompile and relink your application if you use an older release. Upgrading Tuxedo 12.2.2 is not mandatory. For more on Upgrade Considerations, see Upgrade Considerations.
  10. If you already have DMTLOG and TLOG, remove them.
  11. Reboot the application.
  12. Shut down and upgrade the other machines in your configuration as time permits.

Note:

Follow these steps if you are using Tuxedo applications that use XAUTHSVR:
  1. Enter the value of PASSWORD in a plain text.
  2. To encrypt the PASSWORD value in the XAUTHSVR configuration file, run '22c installation dir>/bin/tpldapconf -f XAUTHSVR configuration file>'file.

5.6 Performing Additional Upgrade Steps to Windows Server

For a Windows machine running on Oracle Tuxedo 22c Release 1 (22.1.0.0.0) or earlier software, performs the following additional steps before installing the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) software to ensure that you are starting with a clean system.

  1. Stop the Tuxedo TListen and Oracle procMGR services. From the Start menu, click Start → All Programs → Administrative Tools → Services. The Services window appears.
  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 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. Next, click the Close button.
  3. Run the Windows Add/Remove program to remove the prior Oracle Tuxedo software version. From the Start menu, choose Start → Settings → Control Panel → Add/Remove Programs. The Add/Remove Programs Properties window appears.
  4. Scroll to the entry for the prior Oracle Tuxedo, select it, and click the Add/Remove button.
  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 appears.
  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 the directories contain changes that you made, such as a modified sample file, move the modified files to a temporary location.
  7. Reboot your system after the uninstall completes.

5.7 Upgrading from Tuxedo Previous Releases to Oracle Tuxedo 22c Release 1 (22.1.0.0.0)

If you are upgrading from Oracle Tuxedo previous releases to Oracle Tuxedo 22c Release 1 (22.1.0.0.0), please note the following:

  • In order to allow an Oracle Tuxedo 22c Release 1 (22.1.0.0.0) server to interoperate with Tuxedo 6.5 software, the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) server servopts -toption 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, see GWTDOMAIN(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, And System Processes Reference.
  • In order to allow a domain gateway (GWTDOMAIN) in Oracle Tuxedo 22c Release 1 (22.1.0.0.0) 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 Oracle Tuxedo 22c Release 1 (22.1.0.0.0). 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.
  • In this release, tpreturn() API method throws an exception when an error is encountered. You need to change your existing code to invoke tpreturn() API method in a try-catch block; otherwise, you fail to successfully compile the code.

5.8 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.

5.8.1 Pre-Upgrade Notes

When you migrate the MASTER to Oracle Tuxedo 22c Release 1 (22.1.0.0.0) (through a hot upgrade), you cannot migrate it back to the acting backup until you upgrade the backup to Oracle Tuxedo 22c Release 1 (22.1.0.0.0). Therefore, migrating the MASTER is irreversible; once the migration is complete, the MASTER cannot be reverted to its earlier Oracle Tuxedo release.

When you run tmadmin(1) on an Oracle Tuxedo 22c Release 1 (22.1.0.0.0) machine with a previous release MASTER, the UPGRADE file shown in Hot-Upgrade Example must reside in the current directory. To ensure that the files are in the current directory, you might, for example, run tmadmin from the Tuxedo application directory: $APPDIR (UNIX) directory.

Follow these guidelines when migrating Oracle Tuxedo data storage areas:

  • You must remove the oldTUXCONFIG file. As TUXCONFIG is propagated automatically when the backup machine is run, no action is required on your part.
  • 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, Oracle recommends installing Oracle Tuxedo 22c Release 1 (22.1.0.0.0) on the MASTER machine and backup MASTER, 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 an Oracle Tuxedo 22c Release 1 (22.1.0.0.0) application must 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 do not to recreate them. Furthermore, most applications do not need to add queue space extent in the future or are 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.

If you already have DMTLOG and TLOG, make sure that no pending transaction logs are in them before shutting down the application. In addition, ensure that you remove the DMTLOG and TLOG (if they exist) after the application is shut down.

5.8.2 Hot-Upgrade Procedure

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

  1. Ensure 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.
  2. If upgrading an Oracle Tuxedo 9.1 machine, uninstall the Oracle Tuxedo system software as specified in Uninstalling Oracle Tuxedo.
  3. Shut down the backup MASTER machine.
  4. Install the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) software on the backup MASTER machine and reboot the backup machine.
  5. Migrate the MASTER machine running the old release to the backup MASTER machine running Oracle Tuxedo 22c Release 1 (22.1.0.0.0).
  6. Shut down the machine that is now acting as the backup MASTER.
  7. Install Oracle Tuxedo 22c Release 1 (22.1.0.0.0) on the old MASTER.
  8. Using Oracle Tuxedo 22c Release 1 (22.1.0.0.0), reboot the machine that you shut down in step 7.

For more information about hot upgrades, see Hot-Upgrade Example.

5.8.3 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:
  1. 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
  2. A machine called MACH2 that is configured as the backup.
    • A corresponding application directory called $APPDIR2
    • A corresponding configuration file called $TUXCONFIG2

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

  1. Ensure that your environment has been set up as follows (for MP mode, you must configure the UBBCONFIG file in the $APPDIR of the MASTER machine).
    1. Refer to the ubbmp file of the sample bank application for reference.
    2. In the resource section of the configuration, the BACKUP MASTER machine must be specified. Follow the steps below:
      • Under the *RESOURCES section, select the value of MASTER as MACH1, MACH2 (where, MACH2 is the backup master machine), the following is the example:

        MASTER      MACH1,MACH2

    3. In the configuration, the MODEL option must be set to MP under the *RESOURCES section.
    4. In the configuration, the MIGRATE option must be set.

      OPTIONS         LAN, MIGRATE

    5. Ensure that the Network section is configured with both NADDR and NLSADDR (both must be on separate ports).
      *NETWORK
      MACH1 NADDR="//<MACH1_Hostname>:<naddr_port_number>"
      #BRIDGE="/scratch/<user_name>"
      NLSADDR="//<MACH1_Hostname>:<nls_port_number>"
      MACH2 NADDR="//<MACH2_Hostname>:<naddr_port_number>"
      #BRIDGE="/scratch/user_name"
      NLSADDR="//<MACH2_Hostname>:<nls_port_number>"
    6. Both the MASTER and BACKUP MASTER machines must be installed with the old Tuxedo version.
    7. Start Tlisten on both the MASTER and BACKUP MASTER machines. In the section of UBBCONFIG Network, you must specify the same address as NLSADDR for the tlisten.
    8. Follow the README of the sample application to generate the server and client files, in this case "simpserv" and "simpcl".
  2. Run the Tmboot command on MACH1 after generating the tmconfig file from the above configuration file.
     MACH1> tmloadcf -y ubbmp
  3. The Tmboot on Machine1 (MASTER machine) generates a tmconfig on the BACKUP MASTER machine (MACH2)
  4. Use the following command to shut down the backup MASTER machine from MACH1:
    MACH1> tmshutdown -B MACH2 -l MACH2
  5. Use the following command to kill the tlisten process on the backup master machine (MACH2)  
    ps -ef | grep tlisten 
    kill -9 <pid of the tlisten got from above command>
  6. Install the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) software on the backup MASTER machine.
  7. Cd  $Appdir of MACH2 and rm tuxconfig file.
  8. Prior to running tmconfig to update the APPDIR, TUXCONFIG, and TUXDIR for MACH2 on the UBBCONFIG file available in the MACH1, export EDITOR=vi to enable editing in the vi editor:
    MACH1> tmconfig
    choose option 2)MACHINES
    choose option 5)Update

    TA_LMID<the machine LMID for which you want an update> (You can find the value of LMID in UBBCONFIG file *MACHINES section)

    TA_APPDIR Value of the new appdir
    TA_TUXDIR Value of new tuxdir
    TA_TUXCONFIG value of new TUXCONFIG
    TA_LMID MACH2
    TA_APPDIR     /scratch/<user_name>/oraHome_22c_load11/tuxedo22.1.0.0.0/samples/atmi/simpapp
    TA_APPDIR     /scratch/<user_name>/oraHome_22c_load11/tuxedo22.1.0.0.0
    TA_APPDIR     /scratch/<user_name>/oraHome_22c_load11/tuxedo22.1.0.0.0/samples/atmi/tuxconfig
    
    • Run the command wq! to save and exit
    • Select Y for the confirmation. For more information about tmconfig, see How to Run tmconfig.
    • Run tmunloadcf to verify successful update.
  9. To set PATH, LD_LIBRARY, and TUXDIR to the latest release of Tuxedo, run tux.env from the newly installed Tuxedo product in MACH2.
  10. Ensure TUXCONFIG and APPDIR point to the latest version of Tuxedo.
  11. Use the following command to create a file UPGRADE inside the $APPDIR of MACH2
    touch UPGRADE
  12. In MACH2, export the following Security environment variables:
    export LLE_DEPRECATION_WARN_LEVEL=NONE
    export TM_USE_OLD_CIPHER=Y
    export TM_ALLOW_NOTLS=Y
    export TM_MIN_PUB_KEY_LENGTH=0
    export TM_SECURITY_CONFIG=NONE
  13. Start the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) tlisten in MACH2.
  14. Reboot the backup MASTER machine using the following command from MACH1:
    MACH1> tmboot -B MACH2 -l MACH2 
    verify the tmconfig file generated in this process is located in $APPDIR
  15. Migrate the MASTER machine running the old release to the MASTER machine running the latest release.

    After running the MASTER command, you must not encounter any errors and PSR displays the services running on the machine.

    MACH2> tmadmin
                   master
                   y
                   psr
                   q
  16. Use the following command to kill the tlisten from MACH1:
    ps -ef | grep tlisten
    kill -9 <pid of the tlisten got from above command>
  17. Ensure that Oracle Tuxedo 22c Release 1 (22.1.0.0.0) software is installed on the OLD MASTER machine (MACH1).
  18. Delete the tuxconfig file from $APPDIR of the MACH1 (if it exists).
  19. Run tmconfig file on the MACH 2 to reset the APPDIR, TUXCONFIG, and TUXDIR for MACH1 on the UBBCONFIG file, and then export EDITOR=vi before running tmconfig file to enable the modification to be completed with the vi editor:
    • MACH2> tmconfig
      choose option 2)MACHINES 
      choose option 5)Update

      Pass the following variables in key-value pairs with tab to update the details of a specific machine.

    • TA_LMID MACH1 
      TA_APPDIR Value of the new appdir 
      TA_TUXDIR Value of new tuxdir 
      TA_TUXCONFIG value of new TUXCONFIG
    • Run the command wq! to save and exit.
    • Select Y for the confirmation. For more information about tmconfig, see How to Run tmconfig.
    • Run tmunloadcf to verify successful update.
  20. Set the PATH, LD_LIBRARY, and TUXDIR to the latest release of Tuxedo in MACH1 by running the tux.env file from the newly installed Tuxedo product.
  21. Ensure TUXCONFIG and APPDIR point to the latest version of Tuxedo.
  22. Export the following environment variables in MACH1:
    MACH1>
    export LLE_DEPRECATION_WARN_LEVEL=NONE
    export TM_USE_OLD_CIPHER=Y
    export TM_ALLOW_NOTLS=Y
    export TM_MIN_PUB_KEY_LENGTH=0
    export TM_SECURITY_CONFIG=NONE
  23. Start the Oracle Tuxedo 22c tlisten in MACH1.
  24. Using the following command to reboot the OLD MASTER machine (MACH1) from the MACH2:
    MACH2> tmboot -B MACH1 -l MACH1 
    Verify tmconfig is generated in $APPDIR in this process.
  25. Delete the UPGRADE command from MACHINE2 $APPDIR

5.9 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 22c Release 1 (22.1.0.0.0).

Note:

  • Rebuild is mandatory when upgrading from a previous Oracle Tuxedo version to Oracle Tuxedo 22c Release 1 (22.1.0.0.0). For more information about Upgrading Consideration, see Upgrade Considerations.
  • The TMS server must be rebuilt when upgrading a previous Oracle Tuxedo version to Oracle Tuxedo 22c Release 1 (22.1.0.0.0).

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, can continue to use executable files from an earlier release. For example, even if your MASTER and BACKUP MASTER machines are running Oracle Tuxedo 12.2.2, 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 12c Release 2 (12.2.2) only on Workstation clients, and you do not want to upgrade any of your Oracle Tuxedo system server machines to Oracle Tuxedo 22c Release 1 (22.1.0.0.0), 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 machine is running Oracle Tuxedo 6.5 or later.

5.9.1 Changing from Object Files to Libraries

Some Oracle Tuxedo functions are delivered in object files in the Oracle Tuxedo release 12.1.3 (or lower). In this Oracle Tuxedo release, these object files are packaged in libraries. When rebuilding the corresponding executables, you need to link with the related libraries instead of the object files as listed in the following table:

Table 5-1 Change from Object Files to Libraries

Object File Library Link option (Unix/Linux) Usage
cleanupsrv.o libtux.so / libtux.dll / libtux.sl -ltux cleanupsrv
enqdeqmq.o libtuxmq.so / libtuxmq.dll / libtuxmq.sl -ltuxmq TMQUEUE_MQM
tm_mqi.o libtuxmq.so / libtuxmq.dll / libtuxmq.sl -ltuxmq TM_MQI
tm_mqi_st.o libtuxmq.so / libtuxmq.dll / libtuxmq.sl -ltuxmq TM_MQI
tm_mqo.o libtuxmq.so / libtuxmq.dll / libtuxmq.sl -ltuxmq TM_MQO
tgiopservice.o liborb.so / liborb.dll / liborb.sl -lorb TMIFRSVR
TMQFORWARD.o libqm.so / libqm.dll / libqm.sl -lqm TMQFORWARD
TMQUEUE.o libqm.so / libqm.dll / libqm.sl -lqm TMQUEUE
tpfwinit.o libnative.so / libnative.dll / libnative.sl -lnative TMNTS
tsam_ext.o libtmagent.so / libtmagent.dll / libtmagent.sl -ltmagent Tuxedo service using tsambegin()/tsamend().
usort.o libusort.so / libusort.dll / libusort.sl -lusort  

5.10 Installing Oracle Jolt 22c with Oracle WebLogic Server

This section provides supplementary installation instructions for customers using Oracle Jolt 22c Release 1 (22.1.0.0.0) with Oracle WebLogic Server 9.x, 10.x, 12.1.x, or 14.1.1 and Oracle Tuxedo 9.0, 9.1, 10.0, 10.3, 11.1.1.x, 12.1.1, 12.1.3, 12.2.2 or 22.1.0.0.0.

  1. You can install the Jolt client software on an Oracle WebLogic Server 9.x, 10.x, 12.1.x or 14.1.1 machine by copying the Jolt client software from an Oracle Tuxedo 22c Release 1 (22.1.0.0.0) machine to the target Oracle WebLogic Server machine.

    Note:

    If the Oracle Tuxedo 22c Release 1 (22.1.0.0.0) machine and the target Oracle WebLogic Server machine are the same machine, then you only need to include the Jolt client library class files in your CLASSPATH variable setting.
  2. 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.