During the Oracle Tuxedo software installation, the installer program creates the following directory structure for a full installation. A full installation contains all the Oracle Tuxedo server and client software components plus the Link-Level Encryption (LLE) and Secure Sockets Layer (SSL) encryption software packages.

The following figure illustrates the Oracle Tuxedo 22c Directory Structure:

Figure 6-1 Oracle Tuxedo 22c Release Directory Structure

The product directory shown here, is the default for Oracle Tuxedo 22c Release 1 (22.1.0.0.0). The default name can be changed during installation. The top-level directories and files of the Oracle Tuxedo directory structure are briefly described in the following table:

During the SALT software installation, all SALT files are decompressed within the Oracle Tuxedo TUXDIR directory.

The following table lists brief descriptions of SALT directories and files.

The following image shows an Oracle Tuxedo domain, which is the basis of the Oracle Tuxedo architecture.

Figure 6-2 Simplified View of Oracle Tuxedo Architecture

A Tuxedo domain, also known as a Tuxedo application, is a business software program, built upon the Tuxedo system, that is defined and controlled by a single configuration file—the UBBCONFIG file. A Tuxedo domain consists of many system processes, one or more application client processes, one or more application server processes, and one or more computer machines connected over a network.

There is no need to fully understand these terms now; rather, use the sections as a reference. As you come upon these terms during the post-installation procedures, refer back to these sections to understand exactly what these terms mean.

Each Tuxedo domain is controlled by a configuration file in which installation-dependent parameters are defined. The text version of the configuration file is referred to as UBBCONFIG, although the configuration file may have any name, as long as the content of the file conforms to the format described in reference page UBBCONFIG File in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

The UBBCONFIG file for a Tuxedo domain contains all the information necessary to boot the application, such as lists of its resources, machines, groups, servers, available services, and so on. It consists of nine sections, five of which are required for all configurations: RESOURCES, MACHINES, GROUPS, SERVERS, and SERVICES.

The MASTER machine, or MASTER node, for a Tuxedo domain contains the domain’s UBBCONFIG file, and is designated as the MASTER machine in the RESOURCES section of the UBBCONFIG file. Starting, stopping, and administering a Tuxedo domain is done through the MASTER machine.

In a multi-machine Tuxedo domain running different releases of the Tuxedo system software, the MASTER machine must run the highest release of the Tuxedo system software in the domain.

The TUXCONFIG file is a binary version of the UBBCONFIG file. It is created by running the tmloadcf(1) command, which parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG environment variable. As with UBBCONFIG, the TUXCONFIG file may be given any name.

The MASTER machine for a Tuxedo domain contains the master copy of the TUXCONFIG file. Copies of the TUXCONFIG file are propagated to all other server machines referred to as non-MASTER machines; the Tuxedo system is booted on the MASTER machine.

The TUXCONFIG environment variable defines the location on the MASTER machine where the tmloadcf(1) command loads the binary TUXCONFIG file. It must be set to an absolute pathname ending with the device or system file where TUXCONFIG is to be loaded.

The TUXCONFIG pathname value is designated in the MACHINES section of the UBBCONFIG file. It is specified for the MACHINES machine and for every other server machine in the Tuxedo domain. When copies of the binary TUXCONFIG file are propagated to non-MASTER machines during system boot, the copies are stored on the non-MASTER machines according to the TUXCONFIG pathname values.

The TUXDIR environment variable defines the product installation directory of the Oracle Tuxedo software on the MASTER machine. It must be set to an absolute pathname ending with the name of the product installation directory.

The TUXDIR pathname value is designated in the MACHINES section of the UBBCONFIG file. It is specified for the MASTER machine and for every other server machine in the Tuxedo domain.

You need to set several environment variables before using Oracle Tuxedo to build and run Oracle Tuxedo applications:Table 6-3,Table 6-4, Table 6-5 and Table 6-6.

The following table lists Java Environment Variables.

On a UNIX server machine, set and export the following environment variables shown in the following table to set up your environment:

Examples of TUXDIR, APPDIR, and TUXCONFIG are:

TUXDIR=/home/Oracle/tuxedo22cR1 
APPDIR=/home/me/simpapp 
TUXCONFIG=$APPDIR/tuxconfig

The TUXDIR, APPDIR, and TUXCONFIG environment variables must match the values of the TUXDIR, APPDIR, and TUXCONFIG parameters in the MACHINES section of the UBBCONFIG file. A Bourne shell script named tux.env, located in the Oracle Tuxedo product directory, serves as a model for setting these and other environment variables on a UNIX system.

You, as the application administrator, must start a tlisten process on each machine of a networked Oracle Tuxedo application before the application is booted. The tlisten process enables you and the Oracle Tuxedo software running on the MASTER machine to start, shut down, and administer Oracle Tuxedo processes running on the non-MASTER machines. For example, tmboot(1) can start Oracle Tuxedo system servers on the non-MASTER machines. Generally, one tlisten process is required for each Oracle Tuxedo application running on a server machine.

In addition to the installer program starting a tlisten process on port 3050 during the installation of Oracle Tuxedo, a tlisten process may be started as shown in the following table.

In all cases, the same basic syntax is used to invoke tlisten.

%TUXDIR%\bin\tlisten -l nlsaddr [-u appuid] (Windows) 
$TUXDIR/bin/tlisten [-d devname] -l nlsaddr [-u appuid] (UNIX)

The -l option is required. The argument to -l must match the value of the NLSADDR parameter in the NETWORK section of the UBBCONFIG file. For information on determining the value of NLSADDR, see reference page UBCONFIG(5) in OracleTuxedo File Formats, Data Descriptions, MIBs, and System Processes.

The value of devname is the device name of the network provider; for example, Starlan. If the tlisten process is operating with Sockets, the -d option is not needed.

The value of appuid is the user identifier (UID), or login name, of the Oracle Tuxedo application administrator. It must match the value of the UID parameter in the RESOURCES section of the UBBCONFIG file.

On a UNIX machine, use the -u appuid option when the command is part of an installation script run by user root. This is done to run the tlisten process with the effective UID of the owner of the Oracle Tuxedo software installation on this machine.

If tlisten is started by the Oracle Tuxedo application administrator, either as a cron job or manually, the -u option is not mandatory since the job is already owned by the correct account.

For more information about the tlisten(1) command, see reference page in Oracle Tuxedo Command Reference.

Oracle Tuxedo uses the administrative password that you specified during the installation to protect the machine on which Oracle Tuxedo is installed from administrative requests and operations (such as tmboot(1)) that are not authorized. Whenever administrative communications arrive on this machine through tlisten(1) gateway processes, Oracle Tuxedo authenticates them by means of the password.

A common password is required for two machines in an Oracle Tuxedo application to communicate successfully. For this reason, you must use the same password whenever you install Oracle Tuxedo on multiple machines for a single application. If during the Oracle Tuxedo installation process you use a different password for one machine, you must add that password using the tlistpwd(1) $TUXDIR utility to thetlisten.pw file on each machine that communicates with each other.

For these reasons, you may have more than one administrative password in your tlisten.pw file. A single password file may contain no more than 20 passwords, with one password per line.

Each Oracle Tuxedo application is controlled by a configuration file in which installation-dependent parameters are defined. In the Oracle Tuxedo documentation, this file is referred to as UBBCONFIG, but you can give your configuration file any name you like as long as the content of the file conforms to the format described in reference page UBBCONFIG(5) in OracleTuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference. Typical configuration filenames begin with the string ubb, followed by a mnemonic string, such as simple in the filename ubbsimple.

As an example, consider ubbsimple, the UBBCONFIG file for the rudimentary ATMI-based simpapp application delivered with the Oracle Tuxedo installation. On a Windows system, this application is found in the directory %TUXDIR%\samples\atmi\simpapp; on a UNIX system, it is found in the directory $TUXDIR/samples/atmi/simpapp.

The following example ubbsimple file has been modified from the ubbsimple file delivered on a UNIX system to include example pathname values for both Windows and UNIX systems.

#ident “@(#)apps:simpapp/ubbsimple $Revision: 1.3 $ 
#Skeleton UBBCONFIG file for the Tuxedo Simple Application. 
#Replace the <bracketed> items with the appropriate values. 
*RESOURCES IPCKEY <Replace with a valid IPC Key> 
#Example: 
#IPCKEY 123456 
DOMAINID simpapp 
MASTER simple 
MAXACCESSERS 10 
MAXSERVERS 5 
MAXSERVICES 10 
MODEL SHM 
LDBAL N 
*MACHINES 
DEFAULT: 
APPDIR=“<Replace with the current directory pathname>” 
TUXCONFIG=“<Replace with your TUXCONFIG Pathname>” 
TUXDIR=“<Directory where Tuxedo is installed>”  
#UNIX 
  #Example: 
  # APPDIR=“/home/me/simpapp” 
  # TUXCONFIG=“/home/me/simpapp/tuxconfig” 
  # TUXDIR=“/home/oracle/tuxedo12cR1” 
<Machine-name> LMID=simple 
#Example:
  #beatux LMID=simple 
*GROUPS 
GROUP1 LMID=simple GRPNO=1 OPENINFO=NONE 
*SERVERS 
DEFAULT: 
CLOPT=“-A” 
simpserv SRVGRP=GROUP1 SRVID=1 
*SERVICES 
TOUPPER

In the configuration file for your application, you must replace the strings enclosed in angle brackets with values specific to your application. The following table provides a sample of the parameters that must be defined in every configuration file.

You must define APPDIR, TUXCONFIG, and TUXDIR for every machine in your Oracle Tuxedo application. If you need to look up other parameters when editing your UBBCONFIG file, see reference page UBBCONFIG(5) in OracleTuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

You must edit your UBBCONFIG file before running tmloadcf(1) to verify the IPC requirements in the section that follows. If you run tmloadcf without first editing the UBBCONFIG file, the command fails with syntax errors.

The TYPE parameter in the MACHINES section of a configuration file specifies the invocation of the External Data Representation (XDR) encode/decode routines when messages are passed between unlike machines. The term “unlike” applies even to machines of the same type if the compiler on each machine is different. In such a case, give each machine a unique TYPE string to force every message to go through the encode/decode routines.

The Oracle Tuxedo system uses interprocess communications (IPC) resources heavily. On many systems, the default values for the parameters that control the size and quantity of the various IPC resources are below the minimums needed to run even a modest Oracle Tuxedo application. Therefore, you may need to reset some parameters. After editing your UBBCONFIG file, you should determine whether you have enough IPC resources for your application.

To perform this task, enter the following tmloadcf(1) command, specifying your edited UBBCONFIG file as input:

tmloadcf -c UBBCONFIG

With the-coption, the tmloadcf program prints a list of the minimum IPC resources required for your application, but does not create or update the TUXCONFIG file. The following is an output report based on the values in ubbsimple.

Output Produced by tmloadcf -c
Ipc sizing (minimum /T values only)... 
Fixed Minimums Per Processor 
SHMMIN: 1 
SHMALL: 1 
SEMMAP: SEMMNI 
Variable Minimums Per Processor 
SEMUME, A SHMMAX SEMMNU, * * 
Node SEMMNS SEMMSL SEMMSL SEMMNI MSGMNI MSGMAP SHMSEG 
------ ------ ------ ------ ------ ------ ------ ------ 
sftuxe 17 5 12 A + 1 13 26 75K 
where 1 <= A <= 8. 
The number of expected application clients per processor should be added to each MSGMNI value.

The output report identifies IPC resources by their traditional UNIX names. To map the traditional names to the names specific to a UNIX platform, see the data sheet for that platform in Oracle Tuxedo 22c Release (22.1.0.0.0) Platform Data Sheets.

The example output report indicates that to run simpapp, your system must have SEMUME, SEMMNU, and SEMMNS set to no less than 17. SEMMSL must be at least 5, and SEMMNI and SEMMAP at least 4 (assuming the value of A is 3). MSGMNI must be at least 13, and MSGMAP at least 26. Finally, the product of SHMMAX and SHMSEG must be at least 75K bytes.

The IPC values are application-dependent, and the numbers in this example reflect a very small configuration. If other client or server applications that use IPC resources are running on the same system with an Oracle Tuxedo application, then the requirements of both applications must be satisfied. Keep in mind also that every machine participating in an application must have sufficient IPC resources available.

If the current IPC resources are inadequate, you must increase the values of the associated IPC parameters.

For instructions on changing the current IPC values for a UNIX system, see the data sheet for your platform in Oracle Tuxedo 22c Release (22.1.0.0.0) Platform Data Sheets.

You create the Universal Device List (UDL) and define a UDL entry for the global transaction log (TLOG) on each machine in your application that uses global transactions. The TLOG is a log file in which information about transactions is kept until the transaction is completed.

Before creating the UDL and defining UDL entries for TLOG, you must set the following parameters in the MACHINES section of the UBBCONFIG file for each machine in your application that uses global transactions. The following table lists the parameters:

Because the TLOG seldom needs to be larger than 100 blocks (pages) and because disk partitions are always substantially larger than that, it may make sense to use the same device for both the TUXCONFIG file and the TLOG. If so, the pathname of the device needs to be specified by both the TUXCONFIG and the FSCONFIG environment variables.

You must manually create a UDL entry for the TLOGDEVICE on each machine where a TLOG is needed. You may create these entries either before or after you have loaded TUXCONFIG, but you must create these entries before booting the application.

To access the create device list command, crdl, you invoke tmadmin -c with the application inactive. The -c option invokes tmadmin in configuration mode.

To create the UDL and a UDL entry for TLOG on each machine in your application that use global transactions, follow these steps:

1. Log in as the application administrator on the MASTER machine.
2. Enter the following command:

   
   tmadmin -c 
   crdl -z config -b blocks

   Here -z config specifies the full pathname of the device on which the UDL should be created (that is, where the TLOG resides), and -b blocks specifies the number of blocks to be allocated on the device. The value of config should match the value of the TLOGDEVICE parameter in the MACHINES section of the UBBCONFIG file. The blocks must be larger than the value of TLOGSIZE. If -z is not specified, the value of config defaults to the value of the FSCONFIG environment variable.

3. Log in as the application administrator on each remaining non-MASTER machine that uses global transactions and repeat step 2.

If the TLOGDEVICE is mirrored between two machines, step 3 is not required on the paired machine. To be recoverable, the TLOG should reside on a device that can be mirrored.

One of the ways to verify that your Oracle Tuxedo software is installed correctly is to run one or more of the sample applications included with the installation. The sample applications demonstrate the capabilities of the ATMI and CORBA clients, and the ATMI and CORBA C++ servers.

The following sections provide procedures for verifying both the ATMI and CORBA C++ parts of your Oracle Tuxedo installation:

• Running simpapp to Verify the Oracle Tuxedo ATMI Software Installation
• Running simpapp to Verify the Oracle Tuxedo CORBA C++ Software Installation

The simpapp application is a non-distributed application, meaning that it runs on a single machine. It is designed so that it can be up and running within minutes after the Oracle Tuxedo software is installed.

The simpapp application offers a single service called TOUPPER, which converts strings from lowercase to uppercase. The client is invoked with a single argument: a lowercase string to be converted to uppercase. The server returns the converted string to the client, and the client prints the converted string.

simpcl “hello world”

 Returned string is: HELLO WORLD

Two versions of simpapp exist: an ATMI version and a CORBA version. The ATMI version consists of an ATMI server, an ATMI client, and a UBBCONFIG file. The CORBA version consists of a CORBA C++ server, a CORBA C++ client.

To verify that you have successfully installed the Oracle Tuxedo CORBA C++ software on your system, run the CORBA version of the simpapp application, which on a UNIX system can be found in the directory $TUXDIR/samples/corba/simpapp. The procedure presented in the following two sections is also provided in the README file in the simpapp directory, and in Tutorial for simpapp, a Simple C Application in Tutorials for Developing Oracle Tuxedo ATMI Applications.

• Running simpapp to Verify the Oracle Tuxedo CORBA C++ Software Installation on a UNIX System
  

For Oracle Tuxedo applications that use distributed transactions and XA-compliant resource managers, you must use the buildtms command to construct a transaction manager server load module. This requirement exists on UNIX systems. When the module has been created, it must reside in the directory $TUXDIR/bin on UNIX systems.

If you run the CORBA C++ University sample applications, each sample’s make file creates the TMS load module for you and calls it tms_ora.exe. Therefore, running buildtms as a separate step is necessary only if you do not plan to run any of these sample applications.

For information about the buildtms command with Oracle Tuxedo applications, see reference page buildtms(1) in Oracle Tuxedo Command Reference.

• Running simpapp to Verify the Oracle Tuxedo ATMI Software Installation
  

Uninstalling Oracle Tuxedo 22c Release 1 (22.1.0.0.0) does not remove the Oracle Home directory associated with the installation but does remove all Oracle Tuxedo components installed by the installer program. The uninstallation also removes the product directory associated with the installation.

After launching OUI, the Welcome screen appears. Click Deinstall Products. Select the product(s) you want to remove from the Contents tab of the Inventory panel and click Remove.

You can also remove Oracle homes in the same manner. After you have removed an Oracle home, you can reuse its name and location to install other products. Then confirm the deinstallation. After the selected products are deinstalled, the Inventory panel appears.

When you start the Oracle Tuxedo Installation program on system that already has a copy of Oracle Tuxedo installed, the installation program detects the existing Oracle Tuxedo home directory and displays a warning that the selected ORACLE_HOME already installed Tuxedo. If you want to continue the installation, the components which not exist in the selected ORACLE_HOME are installed. Existing Tuxedo component are not reinstalled by default.