[Top] [Previous Page] [Next Page] [Bottom]

Chapter 4. Starting and Shutting Down Applications

This chapter describes how to ensure that your application is ready to be booted, how to boot it, and how to shut it down. There are also procedures that help you resolve some problems you may run into when you first begin to start and shut down your BEA TUXEDO system application.

Topics covered in this chapter are:

Starting Applications

Before you issue the command to start an application, make sure you have completed all of the tasks in the prerequisite checklist, described in the following section.

Prerequisite Checklist

Complete the following tasks before booting your application.

**Table 4-1 Preliminary Tasks**
Task	Procedure
1	Set Environment Variables
2	Create TUXCONFIG
3	Propagate the BEA TUXEDO Software
4	Create a TLOG Device
5	Start tlisten at All Sites (MP environments)

Set Environment Variables

Set and export variables TUXDIR, TUXCONFIG, PATH, and LD_LIBRARY_PATH so that they are in your environment as the system is booted. For example:

$TUXDIR=<path_name_of_TUX_home_directory>
$TUXCONFIG=<path_name_of_TUXCONFIG>
$PATH=$PATH:$TUXDIR/bin
$LD_LIBRARY_PATH=<path_name_of_shared_libraries>
export TUXDIR TUXCONFIG PATH LD_LIBRARY_PATH

Replace the substitutable strings (shown in italic) with the path names appropriate for your installation. Other environment variables can be specified in an ENVFILE. (See ubbconfig(5).)

On AIX, LIBPATH must be set instead of LD_LIBRARY_PATH. On HPUX, SHLIB_PATH must be set instead of LD_LIBRARY_PATH. On NT, no variable for shared libraries is required.

Create TUXCONFIG

TUXCONFIG is a binary version of the text configuration file. The tmloadcf(1) command converts the configuration file to binary form and writes it to the location given in the TUXCONFIG variable.

Enter the command as follows:

$ tmloadcf [-n] [-y] [-c] [-b blocks] {ubbconfig_file | - }

Note: You must be logged in on the MASTER machine and have the effective user ID of the owner of the configuration file.

You may want to consider the following options before you create TUXCONFIG:

-c

Calculate minimum IPC resources of the configuration.
-n Do a syntax check only; report errors.

The -c and -n options do not load the TUXCONFIG file.

UNIX IPC resources are platform specific. If you use the -c option, check the platform data sheet for your platform in Appendix A of the BEA TUXEDO Installation Guide to judge whether you need to make some changes. If you do want to change IPC resources, check the administration guide for your platform.

If the -n option indicates syntax errors in the configuration file, correct the errors before you proceed.

For ubbconfig_file, substitute the fully qualified name of your configuration file.

When you are ready to create the TUXCONFIG file, you may want to consider the following options:

-b

Limit the size of the TUXCONFIG file.
-y Overwrite the existing TUXCONFIG file without asking.

The -b option takes an argument that limits the number of blocks used to store the TUXCONFIG file. Use it if you are installing TUXCONFIG on a raw disk device that has not been initialized. The option is not recommended if TUXCONFIG will be stored in a regular UNIX system file.

Propagate the BEA TUXEDO Software

TUXCONFIG is automatically propagated to all machines in your configuration by the BEA TUXEDO system software when you run tmboot(1), but there are other files that need to be present on all machines. Table 4-2 is a list of files and directories needed for a networked application.

Table 4-2 **Propagating Directories or Files**
Directory or File	Comments
`APPDIR`	The directory named in the `APPDIR` variable must be created on each node. It is helpful if this directory has the same path name on all nodes.
Executables	Application servers must be built once for each platform type, and must be manually propagated to other machines of that platform (that is, BEA TUXEDO does not do this automatically). Store the executables in `APPDIR`, or in a directory pointed to in a `PATH` variable in `ENVFILES` in the `MACHINES` section.
Field tables `VIEW` files	Depending on the requirements of application services (that is, if FML or `VIEWS` buffer types are used), field tables and `VIEW` description files must be manually propagated to machines where they are used, then recompiled. Use `mkfldhdr`(1) to make a header file out of a field table file; use `viewc`(1) to compile a `VIEW` file. The FML field tables and `VIEW` description files should be available through the environment variables `FLDTBLDIR`, `FIELDTBLS`, `VIEWDIR`, and `VIEWFILES`, or their 32-bit equivalents.
`tlisten`	The `tlisten` process must be started on each machine of a networked BEA TUXEDO application. See `tlisten`(1). The `tlisten` process must be started before the application is booted. Note: You must define `TUXDIR`, `TUXCONFIG`, `APPDIR`, and other relevant environment variables before starting `tlisten`.

Create a TLOG Device

To create distributed transaction processing, you must have a global transaction log (TLOG) on each participating machine. To define a TLOG, you must set several parameters in the MACHINES section of the configuration file. You must create the device list entry for the TLOGDEVICE on each machine where a TLOG is needed. It can be done before or after TUXCONFIG has been loaded, but must be done before the system is booted.

To create an entry in the UDL for the TLOG device:

On the master node with the application inactive, invoke tmadmin -c.
The -c option brings tmadmin up in configuration mode.
Enter the command:
```
crdl -z config -b blocks
```
where -z config specifies the full path name for the device where 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. If config is not specified, it defaults to the value of the variable FSCONFIG (which points to the application's databases).
Repeat Steps 1 and 2 on each node of your application that is expected to be involved with global transactions.

If the TLOGDEVICE is mirrored between two machines, Step 3 is not required on the paired machine. To be recoverable, the TLOG should preferably be on a device that can be mirrored. Because the TLOG is too small (typically,100 pages) to warrant having a whole disk partition to itself, the expectation is that the TLOG will be stored on the same raw disk slice as the application's databases. FSCONFIG is the environment variable used by the system. Therefore, the tmadmin crdl command defaults to FSCONFIG.

Start tlisten at All Sites

To have a networked application, a listener process must be running on each machine.

This step is required if you are running the application on more than one machine, as established by the MODEL MP parameter in the RESOURCES section of the application's UBBCONFIG file.

Note: You must define TUXDIR, TUXCONFIG, APPDIR, and other relevant environment variables before starting tlisten.

The port on which the process is listening must be the same as the port specified for NLSADDR in the NETWORK section of the configuration file. On each machine, use the tlisten(1) command, as follows:

tlisten [ -d device ] -l nlsaddr [-u {uid-# | uid-name}] [ -z bits\ ] [ -Z bits ]

The options to this command are as follows.

-d device

The full path name of the network device. For the BEA TUXEDO system version 6.4 or above, this option is not required. For earlier versions of the BEA TUXEDO system (v6.3 and lower), some network providers (TCP/IP, for example) require this information.

-l nlsaddr

The network address as specified for this machine (LMID) in the NETWORK section of the configuration file. nlsaddr can be specified in any of the formats that can be specified for the NADDR parameter in the same section. If the address has the form 0xhex-digits or \\xhex-digits, it must contain an even number of valid hexadecimal digits.

TCP/IP addresses may be in the //#.#.#.#:port format or the //machine-name:port format.

tmloadcf(1) prints an error if nlsaddr is missing from any entry but the entry for the MASTER LMID, for which it prints a warning. However, if nlsaddr is missing from the MASTER LMID entry, tmadmin(1) is not able to run in administrator mode on remote machines; it will be limited to read-only operations. This also means that the backup site is unable to reboot the master site after failure.

-u uid-# or uid-name

Can be used to have the tlisten process run as the indicated user. This option is required if the tlisten(1) command is run by root on a remote machine.

-z [bits]

When establishing a network link between a BEA TUXEDO administrative process and tlisten, require at least this minimum level of encryption. Zero (0) means no encryption, while 40 and 128 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, link establishment fails. The default is zero.

-Z [bits]

When establishing a network link between a BEA TUXEDO administrative process and tlisten, allow encryption up to this level. Zero (0) means no encryption, while 40 and 128 specify the length (in bits) of the encryption key. The default is 128. The -z and -Z options are available only if either the International or Domestic BEA TUXEDO Security Add-on Package is installed.

Booting the Application

Once the preliminaries have been successfully completed, you are ready to bring up the application, as described in the following section.

Using tmboot

The user who created the TUXCONFIG file is considered the administrator of the application. Only this user can execute tmboot(1).

The application is normally booted from the machine designated as the MASTER in the RESOURCES section of the configuration file or the BACKUP MASTER acting as the MASTER. The -b option allows some deviation from this rule.

For tmboot(1) to find executables, the BEA TUXEDO system processes, such as the BBL, must be located in $TUXDIR/bin. Application servers should be in APPDIR as specified in the configuration file.

When booting application servers, tmboot(1) uses the CLOPT, SEQUENCE, SRVGRP, SRVID, and MIN parameters from the configuration file.

Application servers are booted in the order specified by their SEQUENCE parameter, if SEQUENCE is used. If SEQUENCE is not specified, servers are booted in the order in which they appear in the configuration file.

The command line should look something like the following (this is a greatly simplified example):

$ tmboot  [-g grpname] [-o sequence] [-S] [-A] [-y]

The options shown have the meanings listed in Table 4-3.

**Table 4-3 tmboot Options**
Option	Meaning
`-g` `grpname`	Boot all TMS and application servers in groups using this `grpname` parameter.
`-o` `sequence`	Boot all servers in the order shown in their `SEQUENCE` parameter.
`-s` `server-name`	Boot individual servers.
`-S`	Boot all servers listed in the `SERVERS` section.
`-A`	Boot all administrative servers for machines listed in the `MACHINES` section. This ensures that the `DBBL`, `BBL`, and `BRIDGE` processes are started in the proper order.
`-y`	Provides an automatic "yes" response to the prompt that asks if all administrative and application servers should be booted. This prompt appears only if no options that limit the scope of the command (`-g` `grpname`, for example) are specified.

There are many more options than are shown in the example. For a complete listing of the tmboot options, see the tmboot(1) reference page in the BEA TUXEDO Reference Manual.

Default Boot Sequence for a Small Application

The following scenario shows the order of processing when booting a two-machine configuration. This is not a procedure that you have to initiate; it is what the software does if you enter the following command.

prompt> tmboot -y

tmboot comes up on the MASTER site and processes the TUXCONFIG file, creating a "to do" list for itself.
tmboot boots the DBBL on the MASTER machine.
tmboot boots the BBL on the MASTER machine, which creates the shared memory Bulletin Board.
tmboot boots the BRIDGE on the MASTER machine, which establishes its listening address.
tmboot establishes a connection with the remote site tlisten process and propagates the TUXCONFIG file to the remote site if it is not already there.
tmboot boots a BSBRIDGE. The BSBRIDGE establishes a connection back to the BRIDGE process on the MASTER machine.
tmboot boots a BBL. The BBL creates the local Bulletin Board and sends a request to the DBBL via the BSBRIDGE, to register it as a server. The reply from the DBBL contains a complete copy of the MASTER Bulletin Board and the BBL updates its Bulletin Board with the information.
tmboot boots a BRIDGE. The BRIDGE establishes a connection back to the BRIDGE on the MASTER site, at which point it tells the BSBRIDGE to go away since it is no longer needed.
tmboot can then boot the application servers.
tmboot boots the local application servers first, then boots the remote application servers.
tmboot is now finished processing and leaves gracefully.

Optimized Boot Sequence for Large Applications

The boot sequence recommended for larger applications is shown here. This sequence boots entire machines in a single step rather than taking all the steps used to boot two machines in the default sequence. The optimized sequence can be explained as follows.

Boot the entire MASTER machine first. This is done by using the -M -l combination.
Boot the entire remote machine. This is done by using the -B -l combination.

This method is faster because the number of system messages is far smaller. In large applications (more than 50 machines), this method generally reduces boot time by 50%.

In a configuration with a slow network, boot time can be improved by first booting the machines that have higher speed connections to the MASTER machine.

Shutting Down Applications

The tmshutdown(1) command is provided for shutting down an application.

The rules for use of this command are very similar to those of tmboot(1).

Administrators face several problems when shutting down an application. The two most common situations are discussed in the last section of this chapter.

The tmshutdown(1) command is the inverse of the tmboot(1) command. It shuts down part or all of the BEA TUXEDO system application.

When the entire application is shut down, tmshutdown(1) removes the IPC resources associated with the BEA TUXEDO system.

The options used by tmboot(1) for partial booting (-A, -g, -I, -S, -s, -l, -M, -B) are supported in tmshutdown(1). Note that the -b option, which allows tmboot to be used from a non-MASTER machine, is not supported for tmshutdown; the tmshutdown command must be entered from the MASTER (or BACKUP MASTER) machine.

If servers are to be migrated, the -R option must be used. This shuts the servers down without removing the Bulletin Board entries.

If a node is partitioned, tmshutdown(1) with the -P lmid option can be run on the partitioned machine to shut down the servers on that machine.

tmshutdown(1) will not shut down the administrative server BBL on a machine that has clients attached. The -c option can be used to override this feature. This option is needed when a machine must be brought down immediately and the administrator has been unable to contact the clients.

The -w delay option can be used to force a hard shutdown after delay seconds. This option suspends all servers immediately so that additional work cannot be queued. The value of delay should allow time for requests already queued to be serviced. After delay seconds, a SIGKILL signal is sent to the servers. This option enables the administrator to shut down servers that are looping or blocked in application code.

Always check the details of a command such as tmshutdown(1) in the BEA TUXEDO Reference Manual to make sure you have the most recent information on available options.

Using tmshutdown

The user creating the TUXCONFIG file is considered to be the administrator of the application. Only this user can execute tmshutdown(1).

The application can be shut down only from the machine designated as MASTER in the configuration file. When the BACKUP MASTER is acting as the MASTER, it is considered to be the MASTER for shutdown purposes.

The only exception to this rule is a partitioned machine. By using the -p option, the administrator can run the command from the partitioned machine to shut down the application at that site.

Application servers are shut down in the reverse order specified by their SEQUENCE parameter, or by reverse order of their appearance in the configuration file. If some servers have SEQUENCE numbers and others do not, the unnumbered servers are the first to be shut down, followed by the application servers with SEQUENCE numbers (in reverse order). Finally, administrative servers are shut down.

When an application is shut down, all the IPC resources allocated by the BEA TUXEDO system are removed. Note that tmshutdown does not remove IPC resources allocated by the DBMS.

Clearing Common Problems

There are several problems that you may encounter when first working with the BEA TUXEDO system. This section lists and discusses some of the common startup and shutdown problems.

Common Startup Problems

This section describes a few problems you may encounter when starting your first BEA TUXEDO system application. Evidence that a problem exists comes in the form of a message to ULOG, a message to your screen, or both, as follows:

TLOG Not Created

If the transaction log (TLOG) fails to get created, a message is sent to the user log (ULOG).

The message includes the message catalog name, the unique message number within the catalog, and the reason for the failure. For example, one such message is:

CMDTUX 142 ERROR: Identifier for TLOGNAME must be <= len characters in length

TLOGNAME cannot be more than 30 characters long.

Problems of this kind can be avoided if you check the syntax of the TLOG parameters in the MACHINES section of the UBBCONFIG file (see ubbconfig(5)).

Following are other reasons why the TLOG might not get created:

The person entering the command may lack the authority to do so.
File permissions may not allow you to write to the device.
There is not enough space to create the file.

cannot propagate TUXCONFIG file

Following are possible reasons for the failure:

No listener on the remote machine
Mismatched address specifications for the listener on the remote machine
Group ID and/or the user ID are not the same on both machines
Access (permissions) problems

Table 4-4 shows a possible solution for each propagation problem.

**Table 4-4 Possible Solutions to Propagation Failure**
Problem	Solution
Application fails to boot	If `tlisten` password security is enabled, check that the `tlisten` passwords match on both machines. The match is required.
Listener process not started on remote machine	Check that the `TUXDIR`, `TUXCONFIG`, `APPDIR`, and other relevant environment variables are set on the remote machine, before starting the listener. Then use the `tlisten`(1) command to start the listener.
Listener started at address different from the `NLSADDR` in the configuration file	Correct the listener address and rerun the `tlisten`(1) command.
Group ID and/or the User ID are not the same on both machines	Change the IDs to be the same or specify the correct IDs in the `MACHINES` section for that machine.
Wrong permissions on files/directories on remote machine	Change the permissions to the appropriate values.

Common Shutdown Problems

The two most common problems encountered when shutting down applications are shown with solutions in Table 4-5.

**Table 4-5 Two Common Shutdown Problems and Their Solutions**
Problem	Solution
Shutting down administrative servers before application servers	The BEA TUXEDO system does not allow this action because the administrative servers are needed even after all application servers are shut down. If you want to shut down a machine, the application servers must be shut down ahead of the administrative servers. Use the `tmshutdown` `-l`, `-S`, `-s`, `-g`, and `-I` options before `-A`, `-M`, and `-B`.
Unable to shut down a machine with clients attached	As a rule, the BEA TUXEDO system does not allow this. However, if the client cannot be contacted, the `-c` option can be used to shut down the `BBL` while it still has clients attached. There are consequences to client applications that must be considered before taking this action. Try running `tmshutdown` with the `-w` `delay` option to shut down servers forcibly after `delay` seconds, or run `tmshutdown` with the `-c` option to shut down the `BBL,` even though it has clients attached.

[Top] [Previous Page] [Next Page] [Bottom]

Chapter 4. Starting and Shutting Down Applications

Booting the Application

Optimized Boot Sequence for Large Applications

Unable to Propagate the BEA TUXEDO System