![]() |
![]() |
BEA WebLogic Enterprise 4.2 Developer Center |
![]() HOME | SITE MAP | SEARCH | CONTACT | GLOSSARY | PDF FILES | WHAT'S NEW |
||
![]() Administration | TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | INDEX |
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 WLE or BEA TUXEDO applications.
Topics covered in this chapter are:
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.
Complete the following tasks before booting your application:
1
2
3
4
5
Start tlisten at All Sites (MP environments).
Set and export variables Replace text within angle brackets (< >) with values for your installation. Other environment variables can be specified in an On AIX, For WLE Java, verify that the following environment variables were defined by the WLE Java installation procedure:
Starting Applications
Prerequisite Checklist
Table 4-1 Preliminary Tasks
Task
Procedure
Set Environment Variables
TUXDIR
, TUXCONFIG
, PATH
,
and LD_LIBRARY_PATH
so that they are in your environment as the system is booted. For example:
TUXDIR=<pathname to installed WLE or
BEA TUXEDO directory>
TUXCONFIG=<pathname where TUXCONFIG should go> PATH=$PATH:$TUXDIR/bin
LD_LIBRARY_PATH=<pathname to shared libraries>
export TUXDIR TUXCONFIG PATH LD_LIBRARY_PATHENVFILE
. (See ubbconfig(5).)
LIBPATH
must be set instead of LD_LIBRARY_PATH
. On HP UX, SHLIB_PATH
must be set instead of LD_LIBRARY_PATH
. On NT, no variable for shared libraries is required.
JAVA_HOME
, the directory where the JDK is installed
CLASSPATH
, which must point to:
TUXDIR
,
the directory where the WLE software is installed
Then use the new environment variables when you add to your system's PATH, as shown in the following platform-specific examples.
For example, on Windows NT systems:
For example, on Solaris systems:
During the deployment step, you must also define the environment variables Enter the command as follows:
You may want to consider the following options before you create The -c and -n options do not load the UNIX IPC resources are platform specific. If you use the - If the -n option indicates syntax errors in the configuration file, correct the errors before you proceed.
For When you are ready to create the The You must be logged in on the
To enable distributed transaction processing, several parameters in the Follow these steps to create an entry in the Universal Device List (UDL) for the set JAVA_HOME=c:\jdk1.2
set CLASSPATH=.;%TUXDIR%\udataobj\java\jdk\wle.jar;%TUXDIR%\locale\java\wle
set
PATH=%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;%JAVA_HOME%\jre\bin\classic;
%TUXDIR%\lib;%TUXDIR%\bin;%PATH% JAVA_HOME=/usr/kits/jdk1.2
CLASSPATH=.:$TUXDIR/udataobj/java/jdk/wle.jar:$TUXDIR/locale/java/wle
PATH=$JAVA_HOME/bin:$TUXDIR/bin:$PATH
LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/sparc/native_threads:
$JAVA_HOME/jre/lib/sparc/classic:$JAVA_HOME/jre/lib/sparc:$TUXDIR/lib THREADS_FLAG=native
export JAVA_HOME CLASSPATH PATH LD_LIBRARY_PATH THREADS_FLAG
TUXCONFIG
and APPDIR
. These variables are described in subsequent sections of this chapter.
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.
$ tmloadcf [-n] [-y] [-c] [-b
blocks
] {ubbconfig_file
| - }TUXCONFIG
:
Calculate minimum IPC resources of the configuration.
-c-n
Do a syntax check only; report errors.
TUXCONFIG
file.
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.
ubbconfig_file
, substitute the fully qualified name of your configuration file.
TUXCONFIG
file, you may want to consider the following options:
Limit the size of the
-bTUXCONFIG
file.-y
Overwrite the existing TUXCONFIG
file without asking.
-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.
MASTER
machine and have the effective user ID of the owner of the configuration file.
Propagate the Software
TUXCONFIG
is automatically propagated by the WLE or BEA TUXEDO system to all machines in your configuration 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.
Create a TLOG Device
MACHINES
section of the configuration file are used to define a global transaction log (TLOG
). 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.
TLOG
device. Refer to the section "Step 2: Create a UDL Entry" on page 16-10 for details.
tmadmin -c
. -c
option brings tmadmin
up in configuration mode.
where crdl -z config -b blocks
-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).
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
.
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 [ -ddevice
] -lnlsaddr
[-u {uid-#
|uid-name
}] [ -zbits\
] [ -Zbits
]
The options to this command are as follows:
-d
device
-l
nlsaddr
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
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]
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]
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.
Once the preliminaries have been successfully completed, you are ready to bring up the application, as described in the following section:
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 WLE or 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 [-ggrpname
] [-osequence
] [-sserver
] [-S] [-A] [-y]
Table 4-3 describes the tmboot
options shown above.
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.
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
can then boot the application servers.
tmboot
boots the local application servers first, then boots the remote application
servers.
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:
MASTER
machine first. This is done by using the -M -l
combination.
-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.
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 WLE or BEA TUXEDO application.
When the entire application is shut down, tmshutdown
(1) removes the IPC resources associated with the WLE or 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.
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 WLE or BEA TUXEDO system are removed. Note that tmshutdown
does not remove IPC resources allocated by the DBMS.
There are several problems that you may encounter when first working with the WLE system. This section lists and discusses some of the common startup and shutdown problems.
This section describes a few problems you may encounter when starting your first WLE application. Evidence that a problem exists comes in the form of a message to ULOG
, a message to your screen, or both, as follows:
If the transaction log ( 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:
Problems of this kind can be avoided if you check the syntax of the Following are other reasons why the TLOG Not Created
TLOG
) fails to get created, a message is sent to the user log (ULOG
).
CMDTUX 142 ERROR: Identifier for TLOGNAME must be <= len characters in length
TLOGNAME
cannot be more than 30 characters long.
TLOG
parameters in the MACHINES
section of the UBBCONFIG
file (see ubbconfig
(5)).
TLOG
might not get created:
Following are two reasons a server may not start correctly:
Server Not Built Correctly
buildobjserver
fails
buildobjserver
succeeds but the server comes up with the wrong services
An error in this area should be noticed before you attempt to boot a WLE application. buildobjserver
is used to compile application code, combining the interfaces to be offered by a server into the executable module. If the code fails to compile, the causes can be that an incorrect compiler was specified, the needed libraries were not found, needed interface modules were not found, there is a problem in the code, and so forth. Pay close attention to the error messages and consult Creating C++ Server Applications and Creating Java Server Applications.
Problems in this area can often be attributed to an incorrect CLOPT
parameter for the server (CLOPT
is an abbreviation for "command-line options"). The CLOPT
parameter is assigned in the SERVERS
section of the UBBCONFIG
file. It carries command-line options that apply to a server when the server is booted. The options are defined on the servopts
(5) reference page. Refer to this page and the ubbconfig
(5) reference page for help on debugging the problem.
Another cause for a server coming up with the wrong services could be an incorrect specification of services when the server is built. While services are usually in a module of code that has a mnemonic name, there is no requirement that this be the case. Service a
, for example, may actually be performed by function x
, which could lead to an error.
The OPENINFO
string is specified in the GROUPS
section of the UBBCONFIG
file. It carries information needed by servers in the group when they try to open an application database. There is a very specific form for the information that is agreed to by vendors of XA-compliant DBMS; the information is stored in the WLE or BEA TUXEDO system file $TUXDIR/udataobj/RM.
Note:
After changing the OPENINFO
string, BEA recommends that you reboot the servers that use this resource manager (RM).
To clear a problem:
If this does not resolve the problem, go to step 2.
OPENINFO
parameter as specified in the GROUPS
section
of ubbconfig
(5).
If the problem persists, go to step 3.
$TUXDIR/udataobj/RM
to see how the information for your DBMS
needs to be specified.
In a networked application, there are several reasons why the system may not be able to propagate the TUXCONFIG
file. The generic message is as follows:
cannot propagate TUXCONFIG file
Following are possible reasons for the failure:
Table 4-4 shows a possible solution for each propagation problem.
The two most common problems encountered when shutting down applications are shown with solutions in Table 4-5.
Common Shutdown Problems