Now that you have successfully installed BEA TUXEDO, you must set up your system and parts of the BEA TUXEDO system software to prepare for developing or installing your application. This chapter describes the required set-up tasks in the following sections:
Introduction
Before you can invoke BEA TUXEDO system commands you need to set several environment variables. This section describes the environment variables that you must set and export on a UNIX system. If you are using an NT platform, see "Setting Environment Variables" in the BEA TUXEDO for Windows NT User's Guide for instructions.
On a UNIX system you need to set and export several environment variables. The Bourne shell script All examples below assume that you are using the Bourne shell.
Setting Up Your Environment
tux.env, located in the base directory you specified at installation time, serves as a model for setting these variables.
TUXDIR contains the full pathname of the directory in which you installed the BEA TUXEDO system software. For example, if you installed the BEA TUXEDO system in /var/opt/tuxedo, type this:
TUXDIR=/var/opt/tuxedo; export TUXDIR
PATH is the search path for commands. You should include $TUXDIR/bin in your path. For example:
PATH=$PATH:$TUXDIR/bin; export PATH
LD_LIBRARY_PATH (on SVR4-based systems and Solaris 2.5.1), SHLIB_PATH (on HP-UX), and LIBPATH (on AIX) name the search path for dynamic shared libraries. These environment variables are needed only on platforms that support dynamic shared libraries. You should append $TUXDIR/lib to your existing library path. For example, on SVR4-based systems and Solaris 2.5.1, execute this:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TUXDIR/lib; export LD_LIBRARY_PATH
TUXCONFIG contains the full pathname of the binary configuration file of a specific BEA TUXEDO system application. Several BEA TUXEDO system commands expect TUXCONFIG to be set appropriately. For example, if your application's binary configuration file is located in /var/opt/tuxapp1/tuxconfig you should set and export TUXCONFIG as follows:
Each BEA TUXEDO system application has a configuration file, commonly called the As an example, we show the configuration file from the simple application, found in Listing 3-1 shows Edit the configuration file for your application to replace the strings enclosed in angle brackets with values specific to your installation. Here is a description of the kinds of values you need to provide:
Editing a UBBCONFIG File
UBBCONFIG file, which specifies the application parameters that are installation dependent. Typically, the configuration file has a name that begins with ubb and ends with something mnemonic, (for example, ubbsimple). Usually, you must edit this file before you can boot the application.
$TUXDIR/apps/simpapp. The configuration file is called ubbsimple.
ubbsimple as delivered.
Listing 3-1
The
ubbsimple configuration file
#ident "@(#)apps:simpapp/ubbsimple 60.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
MASTER simple
MAXACCESSERS 5
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>"
#Example:
# APPDIR="/home/me/simpapp"
# TUXCONFIG="/home/me/simpapp/tuxconfig"
# TUXDIR="/usr/tuxedo"
<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
IPCKEY
machine_name
uname -n command. If you are using an NT platform and you do not know the node name of your machine, see your system administrator.
APPDIR = string_value
APPDIR refers to directories in which application and administrative servers will be booted. string_value is the absolute pathname of that directory, optionally followed by a colon-separated list of other directory pathnames, on the machine being defined.
TUXCONFIG = string_value
TUXCONFIG is the binary version of the UBBCONFIG file, produced by tmloadcf(1). string_value is the absolute pathname of the file or device of the TUXCONFIG file.
TUXDIR = string_value
If you need to look up other values when editing your configuration file, the complete syntax can be found on the ubbconfig(5) reference page.
Note:
The configuration file must be edited before you use tmloadcf(1) to verify the IPC requirements (see the next section), or tmloadcf will fail with syntax errors.
The BEA TUXEDO system uses UNIX system Interprocess Communications (IPC) resources heavily. On many UNIX system platforms 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 system application, so it becomes necessary to reset some of the parameters. After editing your configuration file, the next step in determining how things stand with your application is to determine if the IPC resources suffice for the application.
To do this, invoke the tmloadcf(1) command, specifying your edited configuration file as input:
tmloadcf -c ubbconfig
An example of the output is shown in Listing 3-2, which is based on the values in ubbsimple.
Listing 3-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 eachMSGMNIvalue.
This output indicates that to run simpapp, your UNIX 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 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.
Of course, the IPC values are application dependent, and the numbers in this example reflect a very small configuration. If other applications that use IPC resources are running on the same system with a BEA TUXEDO system application, then the requirements of both applications must be satisfied. Keep in mind also that every node 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 determining and changing the current IPC values for your platform, see the data sheet for your platform in Appendix A.
The Universal Device List (UDL) is like a map of the BEA TUXEDO system file system. It gets loaded into shared memory when the application is booted. The TLOG refers to a log in which information on transactions is kept until the transaction is completed.
To create the UDL, execute the following command before the application has been booted:
tmadmin -c
crdl -z config -b blocks
where -z config specifies the full pathname for the device where the UDL should be created and -b specifies the number of blocks to be allocated on the device. config should match the value of the TLOGDEVICE parameter in the MACHINES section of the UBBCONFIG file.
Several parameters in the MACHINES section of the UBBCONFIG file are used to define a global transaction log (TLOG). The BEA TUXEDO system administrator must manually create the device list entry for the TLOGDEVICE on each machine where a TLOG is needed. This can be done either before or after TUXCONFIG has been loaded, but it must be done before the system is booted.
To create an entry in the UDL for the TLOG device, create the UDL as described above on each node that will be involved with global transactions. If the TLOGDEVICE is mirrored between two machines, it is not necessary to do this on the paired machine. The BBL then initializes and opens the TLOG during the boot process.
When used in a distributed environment, the BEA TUXEDO system requires the capability to start, shut down, and administer processes on remote nodes running BEA TUXEDO system servers. The tlisten(1) process provides this facility. Once tlisten is running, tmboot(1), for example, can start BEA TUXEDO system servers on remote nodes.
tlisten is a generic listener process that operates with either of the two network interfaces: Sockets or TLI. It runs as a daemon process, and there are several ways it can be started:
cron job
tlisten manually from the command line
In all cases the same basic invocation syntax is used:
Note:
If your system uses an environment variable other than The
The value for Use the The Now that you have successfully installed the BEA TUXEDO system, you need to rebuild all application clients and servers that will execute on systems upgraded to Release 6.5. You should also remove the old If your BEA TUXEDO system applications are distributed, then the master and backup master nodes must run the highest release of BEA TUXEDO in the configuration. Other nodes, including workstation clients, may continue to use executables from the previous release. For example, if your master and backup master are running Release 6.5, then Release 4.2.2 or later may still be used on other nodes.
There is one important exception to the "highest release" rule. If you wish to install Release 6.5 only on workstation clients, but you do not want to upgrade any of your BEA TUXEDO system server nodes to Release 6.5, you may do so. In other words, workstation clients at any release level beginning with 4.2.2 may be intermixed freely in a configuration whose master is running Release 4.2.2 or later.
The BEA TUXEDO system libraries are not thread-safe. This means that either
TUXDIR=tuxdir; export TUXDIR
LD_LIBRARY_PATH=libpath:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
$TUXDIR/bin/tlisten -d devname -l nlsaddr -u appuidLD_LIBRARY_PATH for the shared library path, specify that variable, instead.
-d and -l options are required. The value for -d represents the network provider. The correct values for various platforms are shown in Table 3-1.
Table 3-1 Network devices for tlisten
-l should be the same as that specified for the NLSADDR parameter in the NETWORK section of the configuration file. For information on determining the value of NLSADDR, see the ubbconfig(5) or tlisten(1) reference page, or the BEA TUXEDO Administrator's Guide.
-u appuid option when the command is part of an installation script run by root. The value of appuid is the UID or login name of the BEA TUXEDO system administrator; the numeric version is the same as the value of the UID parameter in the *RESOURCES section of the configuration file. This means that even though the tlisten process is started by root, it runs with the effective UID of the owner of the BEA TUXEDO system installation. If tlisten is started by the BEA TUXEDO system administrator either manually or as a cron job, the -u option is unnecessary, since the job is already owned by the right account.
Using the TYPE Parameter in UBBCONFIG
TYPE parameter in the MACHINES section of a configuration file specifies the invocation of the XDR (EXternal Data Representation) 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 the message to go through the encode/decode routines.
Rebuilding Applications
TUXCONFIG files and reload them using the newly installed tmloadcf(1).
Threaded Access to Libraries