PATH=/usr/sbin:${TUXDIR}/bin:$PATH
LD_LIBRARY_PATH=$APPDIR:$TUXDIR/lib:/lib:/usr/lib:$LD_LIBRARY_PATH

export TUXDIR APPDIR TUXCONFIG WEBJAVADIR PATH LD_LIBRARY_PATH

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 BEA Tuxedo product directory, serves as a model for setting these and other environment variables on a UNIX system.

Starting the tlisten Process

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

In addition to the installer program starting a tlisten process on port 3050 during the installation of BEA Tuxedo, a tlisten process may be started as follows.

tlisten Invocation

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

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 BEA 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 Windows 2000 or 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 BEA Tuxedo software installation on this machine. If tlisten is started by the BEA Tuxedo application administrator, either as a cron job or manually, the -u option is unnecessary because the job is already owned by the correct account.

tlisten Password

BEA Tuxedo uses the administrative password that you specified during the installation to protect the machine on which BEA 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, BEA 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 BEA Tuxedo application to communicate successfully. For this reason, you must use the same password whenever you install BEA Tuxedo on multiple machines for a single application. If, during the BEA Tuxedo installation process, you use a different password for one machine, you must add that password to the tlisten.pw file on each machine with which you want that machine to communicate.

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. You can use a simple text editor to add passwords to the tlisten.pw file.

Editing a UBBCONFIG File

Each BEA Tuxedo application is controlled by a UBBCONFIG file in which installation-dependent parameters are defined. The UBBCONFIG file for an application usually requires editing before the application can be booted.

Each BEA Tuxedo application is controlled by a configuration file in which installation-dependent parameters are defined. The configuration file for an application usually requires editing before the application can be booted. In the BEA Tuxedo documentation, this file is referred to as UBBCONFIG, but you can give your configuration file any name you like. 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 BEA 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 sample listing shows ubbsimple. The examples in the sample listing have 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-2 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:\bea\tuxedo8.0"

  #UNIX
  #Example:
 #               APPDIR="/home/me/simpapp"
 #               TUXCONFIG="/home/me/simpapp/tuxconfig"
 #               TUXDIR="/home/bea/tuxedo8.0"

 <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 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 XDR (EXternal Data Representation) encode and 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 and decode routines.

Checking IPC Requirements

The BEA 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 BEA 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 it does not create or update the TUXCONFIG file.

The following listing is an output report based on the values in ubbsimple.

Listing 6-3 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 example output report indicates that to run simpapp, your system must have SEMUME, SEMMNU, and SEMMNS set to no less than 17. The value of SEMMSL must be at least 5, and that of SEMMNI and SEMMAP, at least 4 (assuming the value of A is 3). The value of MSGMNI must be at least 13, and that of 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 BEA 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.

Creating the Universal Device List and the Transaction Log

You must create a 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.

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. FSCONFIG specifies the absolute pathname of the application's databases on this machine.

Creating the UDL and UDL Entries for TLOG

You must manually create a UDL entry for the TLOGDEVICE on each machine on which 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, 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:

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 BEA 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 BEA Tuxedo installation:

The simpapp application is a nondistributed application, meaning that it runs on a single machine. It is designed in such a way that it can be up and running within minutes after the BEA 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, and a CORBA Java client. Building and running the CORBA Java client requires the installation of JDK 1.3 on your system.

Running simpapp to Verify the BEA Tuxedo ATMI Software Installation

Running simpapp to Verify the BEA Tuxedo ATMI Software Installation on a Windows System

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

Booting all admin and server processes in C:\home\me\atmi\tuxconfig
INFO: BEA TUXEDO(r) System Release 8.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.

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

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

Booting all admin and server processes in /home/me/atmi/tuxconfig
INFO: BEA TUXEDO(r) System Release 8.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.

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

Running simpapp to Verify the BEA 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:

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

Running simpapp to Verify the BEA 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:

Running buildtms and buildXAJS for BEA Tuxedo Applications that Use XA Resource Managers

For BEA 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 applies to both Windows 2000 and UNIX platforms. When the module has been created, it must reside in %TUXDIR%\bin on Windows 2000 systems, and in $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.

Uninstalling BEA Tuxedo

When you uninstall BEA Tuxedo, all components that were installed by the installation process are removed. Configuration and application files that were created after the installation are not removed.

To uninstall BEA Tuxedo, complete the procedure for your platform provided in the following table.

Reinstalling BEA Tuxedo

When you start the BEA Installation program on a system on which a copy of BEA Tuxedo 8.0 is already installed, the BEA Installation program detects the existing installation and provides you with the prompts shown in the following table.