Performing Post-Installation Tasks

The following sections describe the tasks you perform after installing Oracle Tuxedo:

•	Understanding the Oracle Tuxedo Directory Structure

•	Understanding the Oracle Tuxedo Architecture

•	Using the Registry to Further Restrict Access on a Windows System

•	Setting Up Your Environment

•	Starting the tlisten Process

•	Editing a UBBCONFIG File

•	Using the TYPE Parameter in UBBCONFIG

•	Checking IPC Requirements

•	Creating the Universal Device List and the Transaction Log

•	Running simpapp to Verify Your Installation

•	Running buildtms for Oracle Tuxedo Applications That Use XA Resource Managers

•	Uninstalling Oracle Tuxedo

•	Reinstalling Oracle Tuxedo

Understanding the Oracle Tuxedo Directory Structure

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.

Oracle Tuxedo 11g Release 1 (11.1.1.2.0) Directory Structure is shown in Figure 6‑1.

Figure 6‑1 Oracle Tuxedo 11g Release 1 (11.1.1.2.0) Directory Structure

 

 

The product directory shown here, tuxedo11g Release 1 (11.1.1.2.0), is the default for Oracle Tuxedo 11g Release 1 (11.1.1.2.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 Table 6‑1.

 

Table 6‑1 Top-level Directories and Files of the Oracle Tuxedo Directory Structure

Directory Name	Description
samples Note: Samples are not installed unless they are selected during Tuxedo 11gR1 installation.	Contains sample code and resources designed to help you learn how to develop your own applications using Oracle Tuxedo. The samples directory contains the following subdirectories: • atmi A collection of simple applications that demonstrate the many features of the Oracle Tuxedo Application-to-Transaction Monitor Interface (ATMI) server software. • corba A collection of simple applications that demonstrate the many features of the Oracle Tuxedo Common Object Request Broker Architecture (CORBA) C++ server software. • jolt A collection of simple applications that demonstrate the many features of the Oracle Jolt server software.
help	Contains online help files for the Oracle Tuxedo Administration Console.
jre directory	A directory containing the 1.5x version of the Java Runtime Environment (JRE). JRE 1.5.x provides the Java Virtual Machine, or JVM, required by the Oracle Tuxedo installation program. This version of the JRE is included in the Oracle Tuxedo 11g Release 1 (11.1.1.2.0) distribution. It is automatically installed in the Oracle Home directory when you install Oracle Tuxedo. Note: The JRE cannot be used for development. To develop Oracle Tuxedo Java client applications, you must ensure that the Java Development Kit (JDK) is installed on your system.
bin	Contains Tuxedo, Jolt, and SNMP Agent executable programs.
uninstaller	Contains code required to uninstall the Oracle Tuxedo software.
locale	Contains subdirectories to support the localization of system messages. C subdirectory contains message catalogs for the default locale (U.S. English).
cobinclude	Contains .cbl file entries for use in COBOL programs.
lib	Contains compiled object files, including dynamic shared libraries (for platforms on which Oracle Tuxedo uses dynamic shared libraries) and other object files needed to build Oracle Tuxedo clients and servers.
include	Contains C and C++ language header files, as well as OMG IDL files. Includes subdirectories unicode and xercesc; may include subdirectory rpc, depending on the platform.
udataobj	Contains other directories and files required by Oracle Tuxedo. The udataobj directory contains the following subdirectories and files: • security Contains the default Lightweight Directory Access Protocol (LDAP) filter file (bea_ldap_filter.dat) and LLE-related and SSL-related encryption files. • jolt Contains the files for the Oracle Jolt software components that you selected to install. • snmp Contains the etc directory, which in turn contains the SNMP Agent configuration files, MIB files, and other miscellaneous files. • java Contains the classes and Java archive files needed to run Java applications. • webgui Contains the Java and image files for the Oracle Tuxedo Administration Console. • tlisten.pw (file) Contains the tlisten administrative password that you entered during the installation.
tux.env (file)	UNIX systems only: Contains Oracle Tuxedo environment variables for UNIX installations and serves as a model for setting those variables.

Understanding the Oracle Tuxedo Architecture

Figure 6‑2 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.

Other important terms and concepts that you need to know about Oracle Tuxedo before performing post-installation checks are briefly described in the following sections:

•	UBBCONFIG File

•	MASTER Machine

•	TUXCONFIG File

•	TUXCONFIG Environment Variable

•	TUXDIR Environment Variable

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.

UBBCONFIG File

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(5) in OracleTuxedo 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.

MASTER Machine

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.

TUXCONFIG File

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—in a Tuxedo domain whenever the Tuxedo system is booted on the MASTER machine.

TUXCONFIG Environment Variable

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

TUXDIR Environment Variable

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.

Using the Registry to Further Restrict Access on a Windows System

Oracle Tuxedo-provided client programs are run directly by users with the users’ own permissions. In addition, users running native clients (that is, clients running on the same machine on which the server program is running) have access to the UBBCONFIG file and interprocess communication (IPC) mechanisms such as the bulletin board (a reserved piece of shared memory in which parameters governing the application and statistics about the application are stored).

To gain access to the Oracle Tuxedo functionality, native clients join a Oracle Tuxedo application using the identity of the application administrator (tpsysadm). However, because tpsysadm is a trusted user, this setting causes the Oracle Tuxedo system to bypass the user authentication process.

To prevent this lapse in security on your Windows 2003 server machine, follow these steps:

1.	Choose Start →  Run to launch the Run dialog box, enter regEdt32, and click OK to launch the Registry Editor window.

2.	Select HKEY_LOCAL_MACHINE →  Software →  Oracle Systems →  Tuxedo →  10.3.0.0_VS2005.

3.	Select SECURITY →  Permissions.

4.	Disable control for Everyone and allow access only to users with administrative privileges.

Setting Up Your Environment

You need to set several environment variables before using Oracle Tuxedo to build and run Oracle Tuxedo applications. Table 6‑2, Table 6‑3, Table 6‑4, Table 6‑5 list and define many of those environment variables.

 

Table 6‑2 Oracle Tuxedo Core Environment Variables  

Environment Variable	Description
TUXDIR	Absolute pathname of the product directory in which you installed the Oracle Tuxedo software on this machine. TUXDIR must be set on both server and client-only machines.
APPDIR	Absolute pathname of the application directory in which application and administrative servers will be booted on this server machine. APPDIR may be set to more than one application directory.
TUXCONFIG	Absolute pathname of the device or system file where the binary TUXCONFIG file is found on this server machine. The TUXCONFIG file is created by running the tmloadcf(1) command on the UBBCONFIG configuration file.
WEBJAVADIR	Absolute pathname of the Java and image files for the Oracle Tuxedo Administration Console on this server machine.

 

Table 6‑3 Oracle Tuxedo Client-Only Environment Variables

Environment Variable	Description
WSENVFILE	Tuxedo ATMI Workstation (/WS) client: Name of the file in which all environment variables are set for this workstation. There is no default for this variable.
TOBJADDR	Tuxedo remote CORBA client: Address of the Tuxedo server machine’s listener; must match exactly (including case) the host and port specified for the server machine in the UBBCONFIG file.

 

Table 6‑4 COBOL Environment Variables

Environment Variable	Description
COBCPY	Directories that contain a set of the COBOL COPY files to be used by the compiler.
COBOPT	Arguments that you may want to use on the compile command line.

 

Table 6‑5 Java Environment Variables

Environment Variable	Description
JAVA_HOME	Absolute pathname of the Java Development Kit (JDK) 1.5.x installation directory on this machine; needed to build and run Java applications on this machine.*
JDKDIR	Set to JAVA_HOME value.
CLASSPATH	Absolute pathnames to classes and Java archive files on this machine; needed to run Java applications on this machine.
* The Oracle Tuxedo 11g Release 1 (11.1.1.2.0) distribution does not include a JDK.

Setting Environment Variables on a Windows System

On a Windows 2003 server machine, you need to set the following environment variables shown in Table 6‑6 to set up your environment:

 

Table 6‑6 Environment Variables

set TUXDIR=pathname_of_Oracle_Tuxedo_product_directory

set APPDIR=pathname_of_Oracle_Tuxedo_application_directory

set TUXCONFIG=pathname_of_TUXCONFIG_file

set WEBJAVADIR=%TUXDIR%\udataobj\webgui\java

set PATH=%APPDIR%;%TUXDIR%\bin;\bin;%PATH%

Examples of TUXDIR, APPDIR, and TUXCONFIG are:

TUXDIR=C:\Oracle\tuxedo11gR1

APPDIR=C:\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. As an alternative to setting environment variables from a command-line shell, use the Environment page of the Oracle Administration program, described in “Setting and Modifying Environment Variables” in Using Oracle Tuxedo ATMI on Windows.

Windows 2003 Server accesses the required dynamically loadable library files through its PATH variable setting. Specifically, Windows 2000 searches for dynamically loadable library files in the following order:

1.	The directory from which the Oracle Tuxedo application was loaded

2.	The current directory

3.	The Windows system directory (for example, C:\WINDOWS\System32)

4.	The Windows directory (for example, C:\WINDOWS)

5.	The directories listed in the PATH environment variable

For more information about setting environment variables, see “Setting and Modifying Environment Variables” in Using Oracle Tuxedo ATMI on Windows.

Setting Environment Variables on a UNIX System

On a UNIX server machine, set and export the following environment variables shown in Table 6‑7 to set up your environment:

 

Table 6‑7 Environment Variables

TUXDIR=pathname_of_Oracle_Tuxedo_product_directory

APPDIR=pathname_of_Oracle_Tuxedo_application_directory

TUXCONFIG=pathname_of_TUXCONFIG_file

WEBJAVADIR=$TUXDIR/udataobj/webgui/java

PATH=$APPDIR:$TUXDIR/bin:/bin:$PATH

LD_LIBRARY_PATH=$APPDIR:$TUXDIR/lib:/lib:/usr/lib:$LD_LIBRARY_PATH Note: For HP-UX systems only, use SHLIB_PATH instead of LD_LIBRARY_PATH. For AIX systems only, LIBPATH instead of LD_LIBRARY_PATH.

export TUXDIR APPDIR TUXCONFIG WEBJAVADIR PATH LD_LIBRARY_PATH

 

Examples of TUXDIR, APPDIR, and TUXCONFIG are:

TUXDIR=/home/Oracle/tuxedo11gR1

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.

Starting the tlisten Process

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 tlisten Process Table 6‑8.

 

Table 6‑8 tlisten Process

On This Machine . . .	By This Administrator . . .	Using This Method . . .
Windows 2003 server	Oracle Tuxedo application administrator	Listener page of the Oracle Administration program; for details, see “Configuring tlisten Processes to Start Automatically” in Using Oracle Tuxedo ATMI on Windows
		Manually starting a tlisten process from a command-line shell
UNIX server	UNIX system administrator	As part of a UNIX initialization (boot) script
	Oracle Tuxedo application administrator	As a cron job
		Manually starting a tlisten process from a command-line shell

tlisten Invocation

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 UBBCONFIG(5) in OracleTuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

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.

Note:

To obtain the UID on a UNIX system, run the id command.

On a UNIX machine, use the -u appuid option when the command is part of an installation script run by user root 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 unnecessary since the job is already owned by the correct account.

For more information about the tlisten command, see reference page tlisten(1) in Oracle Tuxedo Command Reference. For details on starting the tlisten process on a Windows 2003 server machine, see “Configuring tlisten Processes to Start Automatically” in Using Oracle Tuxedo ATMI on Windows.

tlisten Password

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) or wlisten(1) gateway processes, Oracle Tuxedo authenticates them by means of the password.

A tlisten password must be a string of alphanumeric characters in clear-text format. It may contain no more than 80 characters.

A common password is required for two machines in a 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 the tlisten.pw file on each machine that communicates with eachother.

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.

Note:

The tlisten.pw file is system-encrypted. To add or change passwords, you must use the tlistpwd(1) utility.

Editing a UBBCONFIG File

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.

Listing 6‑1 shows an example ubbsimple file. The example has been modified from the ubbsimple file delivered on a Windows or UNIX system to include example pathname values for both Windows and UNIX systems.

Listing 6‑1 ubbsimple for the ATMI-based simpapp Application

#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>”
#Windows
 #Example:
# APPDIR=“C:\home\me\simpapp”
# TUXCONFIG=“C:\home\me\simpapp\tuxconfig”
# TUXDIR=“C:\oracle\tuxedo11gR1”

 #UNIX
 #Example:
# APPDIR=“/home/me/simpapp”
# TUXCONFIG=“/home/me/simpapp/tuxconfig”
# TUXDIR=“/home/oracle/tuxedo11gR1”

<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. Listing 6‑9 provides a sample of the parameters that must be defined in every configuration file.

 

Table 6‑9 Parameter Sample

This Parameter . . .	Specifies . . .
IPCKEY	A numeric key that identifies the shared memory segment where the structures used by your application are located. The value must be greater than 32,768 and less than 262,143.
machine_name	The node name of the machine. To obtain the node name on a Windows 2003 Server system, see your system administrator. To obtain the node name on a UNIX system, run the uname -n command.
APPDIR = string	A list of one or more directories in which application and administrative servers will be booted on this machine. For Windows, the value of string is the absolute pathname of one directory, optionally followed by a semicolon-separated list of pathnames for other directories on the machine being defined. For UNIX, the value of string is the absolute pathname of one directory, optionally followed by a colon-separated list of pathnames for other directories on the machine being defined.
TUXCONFIG = string	The absolute pathname of the device or system file where the binary TUXCONFIG file is to be created on this machine. The TUXCONFIG file is created by running the tmloadcf(1) command on the UBBCONFIG file.
TUXDIR = string	The absolute pathname of the product directory of the Oracle Tuxedo software on this machine.

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 will fail with syntax errors.

Using the TYPE Parameter in UBBCONFIG

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.

Checking IPC Requirements

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 -c option, the tmloadcf program prints a list of the minimum IPC resources required for your application, but does not create or update the TUXCONFIG file.

Listing 6‑2 is an output report based on the values in ubbsimple.

Listing 6‑2 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 11g Release 1 (11.1.1.3.0) Platform Data Sheets” on page A‑1. To map the traditional names to the names specific to the Windows 2003 Server platform, see the table titled “IPC Resource Name Mappings Between Windows and UNIX Systems” in Using Oracle Tuxedo ATMI on Windows.

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 a 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 Windows 2003 Server system, see “Configuring IPC Resources to Maximize System Performance” in Using Oracle Tuxedo ATMI on Windows. For instructions on changing the current IPC values for a UNIX system, see the data sheet for your platform in “Oracle Tuxedo 11g Release 1 (11.1.1.3.0) Platform Data Sheets” on page A‑1.

Creating the Universal Device List and the Transaction Log

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 will use global transactions. The TLOG is a log file in which information about transactions is kept until the transaction is completed.

Defining the TLOG

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 will use global transactions.

Table 6‑10 lists the parameters.

 

Table 6‑10 Parameter

This Parameter . . .	Specifies . . .
TLOGDEVICE = string	The Oracle Tuxedo filesystem containing the distributed transaction processing (DTP) TLOG for this machine. If not specified, it is assumed that this machine has no TLOG.
TLOGOFFSET = offset	The numeric offset in pages (from the beginning of the device) to the start of the Oracle Tuxedo filesystem containing the DTP transaction log for this machine. The default is 0.
TLOGNAME = string	The name of the DTP transaction log for this machine. If not specified, the default is “TLOG.”
TLOGSIZE = size	The numeric size, in pages, of the DTP transaction log for this machine. If not specified, the default is 100 pages.

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.

Creating the UDL and UDL Entries for TLOG

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 will 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 will reside), 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 will use 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.

Running simpapp to Verify Your Installation

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.

For example, the invocation

simpcl “hello world”

results in the output

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.

Running simpapp to Verify the Oracle Tuxedo ATMI Software Installation

To verify that you have successfully installed the Oracle Tuxedo ATMI software on your system, run the ATMI version of the simpapp application, which on a Windows system can be found in the directory %TUXDIR%\samples\atmi\simpapp, and on a UNIX system can be found in the directory $TUXDIR/samples/atmi/simpapp.

Note:

Samples are not installed unless they are selected to be installed during Tuxedo 11gR1 installation.

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 ATMI Software Installation on a Windows System

To configure and run the ATMI version of simpapp on a Windows system, follow these steps:

1.	Log in to the target machine as the Administrator or as a member of the Administrator group and open a command-line shell.

2.	Create a working directory for your sample application and change to it:

cd C:\home\me
mkdir atmi
cd atmi

3.	Set the environment variables used by the Oracle Tuxedo system, as explained in “Setting Environment Variables on a Windows System” on page 6‑11. Set APPDIR and TUXCONFIG as follows:

set APPDIR=C:\home\me\atmi
set TUXCONFIG=%APPDIR%\tuxconfig

Note:

You do not have to set the WEBJAVADIR environment variable.

4.	Copy the simpapp files to your working directory. You will need to edit one of them: the configuration file, ubbsimple. Check the permissions on all the files in your working directory and, if necessary, change the permissions to allow full access. For example:

copy %TUXDIR%\samples\atmi\simpapp\*.* *.*
attrib -R /S *.*

5.	Compile the simpapp client and server programs by entering the following commands:

buildclient -o simpcl -f simpcl.c
buildserver -o simpserv -f simpserv.c -s TOUPPER

6.	In the sample configuration file, ubbsimple, replace the strings shown in angle brackets with values appropriate to your Oracle Tuxedo system installation. Comments in ubbsimple explain how to customize the file. Set the following parameters in the ubbsimple file:

•	Set IPCKEY to a valid IPC key. This value must be greater than 32,768 and less than 262,143.

•	Set APPDIR to ”C:\home\me\atmi”.

•	Set TUXCONFIG to the literal pathname corresponding to $APPDIR/tuxconfig (in our example, ”C:\home\me\atmi\tuxconfig”).

•	Set TUXDIR to the absolute pathname of the product directory of the Oracle Tuxedo software on this machine (for example, ”C:\oracle\tuxedo11gR1”).

•	Set MACHINE-NAME to the name of your system. MACHINE-NAME must be entered in uppercase letters on a Windows system.

Note:

The APPDIR, TUXCONFIG, and TUXDIR parameter settings in the ubbsimple file must match the APPDIR, TUXCONFIG, and TUXDIR environment variable settings.

7.	Create the binary version of your edited configuration file by invoking tmloadcf(1), which produces a file named tuxconfig. This file, referenced by the TUXCONFIG environment variable, provides the Oracle Tuxedo system with a description of the application configuration at run time:

tmloadcf -y ubbsimple

8.	Boot simpapp by typing the following command:

tmboot -y

If the boot succeeds, output similar to the following appears and you can proceed to step 10.

Listing 6‑3 shows the output produced by tmboot -y.

Listing 6‑3 Output Produced by tmboot -y

Booting all admin and server processes in C:\home\me\atmi\tuxconfig
INFO: Oracle Tuxedo(r) System Release 10.3.0.0
INFO: Serial #: 000102-9125503751, Maxusers 25
Booting admin processes ...
exec BBL -A:
process id=24180 ... Started.
Booting server processes ...
exec simpserv -A :
process id=24181 ... Started.
2 processes started.

 

9.

If the boot fails, examine the log named ULOG.mmddyy in your application directory (%APPDIR%, C:\home\me\atmi). The string mmddyy is a placeholder for the date (digits representing the current month, day, and year) that will make up the end of the filename. If you see a message such as the following, near the end of the log

can’t create enough semaphores for BB

then the interprocess communication (IPC) resources configured in your operating system are not adequate for running simpapp.

To confirm this hypothesis, invoke the Oracle Tuxedo system command tmloadcf(1) and specify the name of your configuration file, as shown in the following example:

tmloadcf -c %APPDIR%\ubbsimple

If the current value of any IPC parameter configured in your operating system is less than a minimum (either variable or fixed) listed in the tmloadcf output, you must increase the value of that parameter. For instructions on determining and changing the current IPC values for your platform, see “Configuring IPC Resources to Maximize System Performance” in Using Oracle Tuxedo ATMI on Windows.

10.	If the boot succeeded, you can invoke the client. For example, enter the following command:

simpcl “hello world”

The following is displayed:

Returned string is: HELLO WORLD

11.	When you have finished, shut down simpapp with the following command:

tmshutdown -y

Running simpapp to Verify the Oracle Tuxedo ATMI Software Installation on a UNIX System

To configure and run the ATMI version of simpapp on a UNIX system, follow these steps:

1.	Log in to the target machine as the Oracle Tuxedo application administrator and open a command-line shell.

2.	Create a working directory for your sample application and change to it:

cd /home/me
mkdir atmi
cd atmi

3.	Set and export the environment variables used by the Oracle Tuxedo system, as explained in “Setting Environment Variables on a UNIX System” on page 6‑12. Set APPDIR and TUXCONFIG as follows:

APPDIR=/home/me/atmi
TUXCONFIG=$APPDIR/tuxconfig
export APPDIR TUXCONFIG

Note:

You do not have to set the WEBJAVADIR environment variable.

4.	Copy the simpapp files to your working directory. You will need to edit one of them: the configuration file, ubbsimple. Make sure that the client and server files, simpcl and simpserv, are executable, and that the configuration file, ubbsimple, is writable. For example:

cp $TUXDIR/samples/atmi/simpapp/* .
chmod 755 simpserv simpcl
chmod 644 ubbsimple

5.	Compile the simpapp client and server programs by entering the following commands:

buildclient -o simpcl -f simpcl.c
buildserver -o simpserv -f simpserv.c -s TOUPPER

6.	In the sample configuration file, ubbsimple, replace the strings shown in angle brackets with values appropriate to your Oracle Tuxedo system installation. Comments in ubbsimple explain how to customize the file. Set the following parameters in the ubbsimple file:

•	Set IPCKEY to a valid IPC key. This value must be greater than 32,768 and less than 262,143.

•	Set APPDIR to ”/home/me/atmi”.

•	Set TUXCONFIG to the literal pathname corresponding to $APPDIR/tuxconfig (in our example, ”/home/me/atmi/tuxconfig”).

•	Set TUXDIR to the absolute pathname of the product directory of the Oracle Tuxedo software on this machine (for example, ”/home/oracle/tuxedo11gR1”).

•	Set MACHINE-NAME to the name of your system.

To determine the name of your system on a UNIX machine enter the command:

uname -n

Note:

The APPDIR, TUXCONFIG, and TUXDIR parameter settings in the ubbsimple file must match the APPDIR, TUXCONFIG, and TUXDIR environment variable settings.

7.	Create the binary version of your edited configuration file by invoking tmloadcf(1), which produces a file named tuxconfig. This file, referenced by the TUXCONFIG environment variable, provides the Oracle Tuxedo system with a description of the application configuration at run time:

tmloadcf -y ubbsimple

8.	Boot simpapp by typing the following command:

tmboot -y

If the boot succeeds, output similar to the following appears and you can proceed to step 10.

Listing 6‑4 shows the output produced by tmboot -y.

Listing 6‑4 Output Produced by tmboot -y

Booting all admin and server processes in /home/me/atmi/tuxconfig
INFO: Oracle Tuxedo(r) System Release 10.3.0.0
INFO: Serial #: 000102-9125503751, Maxusers 25
Booting admin processes ...
exec BBL -A:
process id=24180 ... Started.
Booting server processes ...
exec simpserv -A :
process id=24181 ... Started.
2 processes started.

 

9.

If the boot fails, examine the log named ULOG.mmddyy in your application directory ($APPDIR, /home/me/atmi). The string mmddyy is a placeholder for the date (digits representing the current month, day, and year) that will make up the end of the filename. If you see a message such as the following, near the end of the log

can’t create enough semaphores for BB

then the interprocess communication (IPC) resources configured in your operating system are not adequate for running simpapp.

To confirm this hypothesis, invoke the Oracle Tuxedo system command tmloadcf(1) and specify the name of your configuration file, as shown in the following example:

tmloadcf -c $APPDIR/ubbsimple

If the current value of any IPC parameter configured in your operating system is less than a minimum (either variable or fixed) listed in the tmloadcf output, you must increase the value of that parameter. For instructions on determining and changing the current IPC values for your platform, see the data sheet for your platform in “Oracle Tuxedo 11g Release 1 (11.1.1.3.0) Platform Data Sheets” on page A‑1.

10.	If the boot succeeded, you can invoke the client. For example, enter the following command:

simpcl “hello world”

The following is displayed:

Returned string is: HELLO WORLD

11.	When you have finished, shut down simpapp with the following command:

tmshutdown -y

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

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 Windows system can be found in the directory %TUXDIR%\samples\corba\simpapp, and 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 Windows System

To configure and run the CORBA version of simpapp on a Windows system, follow these steps:

1.	Log in to the target machine as the Administrator or as a member of the Administrator group and open a command-line shell.

2.	Create a working directory for your sample application and change to it:

cd C:\home\me
mkdir corba
cd corba

3.	Make sure that the product directory in which you installed the Oracle Tuxedo software is set in the TUXDIR environment variable. For example, if you installed the software in the C:\oracle\tuxedo11gR1 directory, set TUXCONFIG as follows:

set TUXDIR=C:\oracle\tuxedo11gR1

4.	Copy the simpapp files to your working directory and change the permissions on all files to allow full access. For example:

copy %TUXDIR%\samples\corba\simpapp\*.* *.*
attrib -R /S *.*

5.	Ensure that nmake is in your path.

6.	To run simpapp automatically, enter runme. The simpapp application runs and prints the following messages:

Testing simpapp
cleaned up
prepared
built
loaded ubb
booted
ran
shutdown
saved results
PASSED

7.	To run the sample manually to observe the simpapp processes starting and stopping, follow these steps:

a.	Enter results\setenv.

b.	Enter tmboot -y. The application starts several processes.

c.	Enter simple_client. The prompt String? appears.

d.	Enter a word in lowercase letters. The application converts the word to uppercase and then to lowercase letters.

e.	Enter tmshutdown -y. The application shuts down the processes.

8.	To restore the directory to its original state, perform these steps:

a.	results\setenv

b.	nmake -f makefile.nt clean

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

To configure and run the CORBA version of simpapp on a UNIX system, follow these steps:

1.	Log in to the target machine as the Oracle Tuxedo application administrator and open a command-line shell.

2.	Create a working directory for your sample application and change to it:

prompt> cd /home/me
prompt> mkdir corba
prompt> cd corba

3.	Make sure that the product directory in which you installed the Oracle Tuxedo software is set in the TUXDIR environment variable. For example, if you installed the software in the /home/oracle/tuxedo11gR1 directory, set and export TUXCONFIG as follows:

prompt> TUXDIR=/home/oracle/tuxedo11gR1
prompt> export TUXDIR

4.	Copy the simpapp files to your working directory and change the permissions on all files to allow full access. For example:

prompt> cp $TUXDIR/samples/corba/simpapp/* .
prompt> chmod 777 *

5.	Ensure that make is in your path.

6.	To run simpapp automatically, enter ../runme.ksh. The simpapp application runs and prints the following messages:

Testing simpapp
cleaned up
prepared
built
loaded ubb
booted
ran
shutdown
saved results
PASSED

7.	To run simpapp manually to observe the processes starting and stopping, follow these steps:

a.	prompt> ksh

b.	prompt> ../results/setenv.ksh

c.	prompt> tmboot -y

The application starts several processes.

d.	prompt> simple_client

The prompt String? is displayed.

e.	prompt> enter_a_word_in_lowercase_letters

The application converts the word to uppercase and then to lowercase letters and displays the results.

f.	prompt> tmshutdown -y

g.	The application shuts down the processes.

8.	To restore the directory to its original state, follow these steps:

a.	prompt> ../results/setenv.ksh

b.	prompt> make -f makefile.mk clean

Running buildtms for Oracle Tuxedo Applications That Use XA Resource Managers

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 Windows 2003 Server and UNIX systems. When the module has been created, it must reside in %TUXDIR%\bin on Windows 2003 Server systems, or $TUXDIR/bin on UNIX systems.

If you run the CORBA C++ University sample applications, each sample’s makefile 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.

Uninstalling Oracle Tuxedo

Uninstalling Oracle Tuxedo11g Release 1 (11.1.1.2.0), 10.0, 9.1, 9.0, 8.1 or 8.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 unless one of the following is true:

•	The product directory contains customer-created configuration or application files—the uninstallation does not delete customer-created configuration or application files.

•	The uninstall was invoked from within the product directory structure—specifically, within the uninstaller directory.

To uninstall Oracle Tuxedo 11g Release 1 (11.1.1.2.0), complete the procedures for the appropriate platform, provided in Table 6‑11. To uninstall Oracle Tuxedo 9.1 or 10.0, substitute “Tuxedo 9.1 or 10.0” for “Tuxedo 11g Release 1 (11.1.1.2.0)” in Table 6‑11.

 

Table 6‑11 Uninstall Oracle Tuxedo

To Uninstall Oracle Tuxedo on This Platform . . .	Perform the Following Procedure . . .
Windows	1. Shut down any Oracle Tuxedo servers that are running. For instructions on using the tmshutdown command to shut down Oracle Tuxedo applications, see reference page tmshutdown(1) in Oracle Tuxedo Command Reference. 2. From the Windows Start menu, choose Start →  Programs →  Oracle WebLogic E-Business Platform →  Tuxedo 11g Release 1 (11.1.1.2.0) →  uninstall. The Oracle Installation program Uninstaller window appears. 3. Click Uninstall to start the uninstall program. 4. Click Exit in the Uninstall Complete window.
UNIX	1. Shut down any Oracle Tuxedo servers that are running. For instructions on using the tmshutdown command to shut down Oracle Tuxedo applications, see reference page tmshutdown(1) in Oracle Tuxedo Command Reference. 2. Go to the tux_prod_dir/uninstaller directory, where tux_prod_dir represents the product directory in which you installed the Oracle Tuxedo software. 3. Choose one of two methods for uninstalling the software: • To use the GUI-mode installation program, go to step 4. • To use the console-mode procedure, go to step 5. 4. (GUI-mode method) Enter the sh Uninstall_Tuxedo_11gR1 command at the prompt. In the Uninstaller window, click Uninstall to start the uninstall program, then click Exit in the Uninstall Complete window to complete the uninstallation. 5. (Console-mode method) Enter the sh Uninstall_Tuxedo_11gR1 -i console command at the prompt. When the uninstall process is complete, press Enter to exit the uninstaller.

Reinstalling Oracle Tuxedo

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 asks if you want to:

•	Copy the new installation directory over the existing one

•	Create a new installation directory

Table 6‑12 shows the reinstallation screen.

 

Table 6‑12 Reinstalling Oracle Tuxedo

Click . . .	To . . .
Continue	Close the warning window and continue with the installation. This option overwrites the previous installation.
Cancel	Return to the Choose Oracle Home Directory window. To continue installing the software using a different Oracle Home directory, select an existing Oracle Home directory that does not contain the release 11g Release 1 (11.1.1.2.0) software or create a new Oracle Home directory.
Exit	Exit the installation program and uninstall the previous installation. You can invoke the uninstall program as described in “Uninstalling Oracle Tuxedo” on page 6‑31, and reinstall the software as described in one of the following: • “Installing Oracle Tuxedo Using GUI-Mode Installation” on page 2‑1 • “Installing Oracle Tuxedo on UNIX Systems Using Console-Mode Installation” on page 3‑1 • “Installing Oracle Tuxedo Using Silent Installation” on page 4‑1