This topic includes the following sections:
The following flowchart illustrates the tasks required to start up and shut down your BEA Tuxedo application.
Click on each of the following tasks for instructions on completing that task.
Being able to access the BEA Tuxedo executables and data libraries is essential to the job of managing a BEA Tuxedo application. For example, the commands needed to start up or shut down an application are located in %TUXDIR%\bin
on a Windows
host machine, and in $TUXDIR/bin
on a UNIX host machine.
On a Windows host machine, enter the following commands at the command prompt to set up your environment:
set TUXCONFIG=path_name_of_TUXCONFIG_file
set TUXDIR=path_name_of_BEA_Tuxedo_system_root_directory
set APPDIR=path_name_of_BEA_Tuxedo_application_root_directory
set PATH=%APPDIR%
;%TUXDIR%
\bin;%PATH%
Replace the substitutable strings (italicized) with the absolute pathnames appropriate for your installation.
Windows accesses the required dynamically loadable library files through its PATH
variable setting. Specifically, Windows searches for dynamically loadable library files in the following order:
On a UNIX host machine, set and export the following environment variables to set up your environment:
TUXCONFIG=path_name_of_TUXCONFIG_file
TUXDIR=path_name_of_BEA_Tuxedo_system_root_directory
APPDIR=path_name_of_BEA_Tuxedo_application_root_directory
PATH=$APPDIR:$TUXDIR/bin:/bin:$PATH
LD_LIBRARY_PATH=$APPDIR:$TUXDIR/lib:/lib:/usr/lib:$LD_LIBRARY_PATH
export TUXCONFIG TUXDIR APPDIR PATH LD_LIBRARY_PATH
Replace the substitutable strings (italicized) with the absolute pathnames appropriate for your installation.
Note: | The application administrator defines the TUXCONFIG , TUXDIR , and APPDIR environment variables in the MACHINES section of the UBBCONFIG file or the T_MACHINE class of the TM_MIB for each machine in an application. See the UBBCONFIG(5) or TM_MIB(5) reference page for a description of these environment variables. |
Each BEA 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.
The binary version of the UBBCONFIG
file is referred to as TUXCONFIG
. As with UBBCONFIG
, the TUXCONFIG
file may be given any name; the actual name is the device or system filename specified in the TUXCONFIG
environment variable.
Note: | For information about the configuration file, refer to UBBCONFIG(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference. |
The tmloadcf(1) command converts the text configuration file to a binary file called TUXCONFIG
and writes the new file to the location given in the TUXCONFIG
variable. Run the command as follows:
$ tmloadcf [-n] [-y] [-c] [-bblocks
] {UBBCONFIG_file
| - }
Note: | You must be logged in on the MASTER machine and have the effective user ID of the configuration file owner. |
The options shown here perform the following functions:
The -c
and -n
options do not load the TUXCONFIG
file. IPC resources are platform specific. If you use the -c
option, check the data sheet for your platform in the BEA Tuxedo Installation Guide to judge whether you must make changes. If you do want to change IPC resources, check the administration documentation for your platform. If the -n
option checks for syntax errors in the configuration file, correct the errors before you proceed. (For UBBCONFIG_file
, substitute the fully qualified name of your configuration file.)
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
is stored in a regular UNIX system file.
For a networked application, a listener process must be running on each machine. A networked application is an application that runs 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
]
Example: tlisten -l //machine1:6500
-d
device
—the full pathname of the network device. For BEA Tuxedo release 6.4 or later, this option is not required. For earlier versions of the BEA Tuxedo system (up to release 6.3), some network providers (for example, TCP/IP) require this information.-l
nlsaddr
—network address at which the process listens for connections. TCP/IP addresses may be specified in the following forms: "//hostname:port_number"
"//#.#.#.#:port_number"
In the first example, tlisten
finds an address for hostname
using the local name resolution facilities (usually DNS). hostname
must be the local machine, and the local name resolution facilities must unambiguously resolve hostname
to the address of the local machine.
In the second example, the #.#.#.#
is in dotted decimal format. In dotted decimal format, each #
should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine. In both of the above formats, port_number
is the TCP port number at which the tlisten
process listens for incoming requests. port_number
can either be a number between 0 and 65535 or a name. If port_number
is a name, then it must be found in the network services database on your local machine. The address can also be specified in hexadecimal format when preceded by the characters 0x
. Each character after the initial 0x
is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX
or TCP/IP
. The address can also be specified as an arbitrary string.The value should be the same as that specified for the NLSADDR
parameter in the NETWORK
section of the configuration file.
tmloadcf(1) prints an error if nlsaddr
is missing from any entry—except the entry for the MASTER
LMID
, for which it will print a warning. However, if nlsaddr
is missing from the MASTER
LMID
entry, tmadmin(1) cannot be run in administrator mode on remote machines; it is limited to read-only operations. This also means that a backup site is unable to reboot the MASTER
site after failure.
-u
uid-#
or uid-name
—used to run the tlisten
process as the indicated user. This option is required if the tlisten(1) command is run by root on a remote machine. -z [
bits
]
—specifies the minimum level of encryption required when establishing a network link between a BEA Tuxedo system administrative process and tlisten
. Zero (0) means no encryption, while 56 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
]
—specifies the maximum level of encryption allowed when establishing a network link between a BEA Tuxedo system administrative process and tlisten
. Zero (0) means no encryption, while 56 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 U.S. and Canada BEA Tuxedo Security license is installed.
TUXCONFIG
is propagated automatically to all machines in your configuration by the BEA Tuxedo system when you run tmboot(1). There are, however, other files that you need to propagate manually. Following is a list of the files and directories that you need to create for a networked application. First, install the BEA Tuxedo system on the machine.
Note: | The tlisten process must be started on each machine of a networked BEA Tuxedo application before the application is booted. Refer to the tlisten(1) reference page. |
Note: | You must define TUXDIR , TUXCONFIG , APPDIR , and other relevant environment variables before starting tlisten . |
You must build one set of application servers for each platform, and manually propagate the appropriate set to all machines running on each platform (that is, the BEA Tuxedo system does not do this automatically). Store the executables in
APPDIR , or in a directory specified in a PATH variable in ENVFILES in the MACHINES section of your configuration file.
|
|
If
FML or VIEWS buffer types are used, field tables and VIEW description files must be manually propagated to the machines where they are used, and then recompiled. Use mkfldhdr, mkfldhdr32(1) to make a header file out of a field table file; use viewc, viewc32(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.
|
To create distributed transaction processing, you must have created a global transaction log (TLOG
) on each participating machine. To define a TLOG
, complete the following steps.
MACHINES
section of the configuration file: TLOGDEVICE
, TLOGOFFSET
, TLOGNAME
, and TLOGSIZE
.TLOGDEVICE
on each participating machine. (You can do this task before or after loading TUXCONFIG
, but you must do so before booting the system.) To create an entry in the UDL for the TLOG
device, invoke tmadmin -c
on the MASTER
machine with the application inactive. (The -c
option invokes tmadmin
in configuration mode.)crdl -zconfig
-bblocks
where -z
config
specifies the full pathname for 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. The blocks must be larger than the TLOGSIZE
. If -z
is not specified, the value of config
defaults to the value of the variable FSCONFIG
(which points to the application's databases).
If the TLOGDEVICE
is mirrored between two machines, step 4 is not required on the paired machine. To be recoverable, the TLOG
should reside on a device that can be mirrored. Because the TLOG
is too small (typically, 100 pages) to warrant the allocation of a whole disk partition, the TLOG
is commonly stored on the same raw disk slice as the BEA Tuxedo /Q database.
Once all prerequisites have been completed successfully, you can bring up the application using tmboot
. Only the administrator who created the TUXCONFIG
file can execute tmboot(1).
The application is generally booted from the machine designated as MASTER
in the RESOURCES
section of the configuration file or the BACKUP
acting as the MASTER
. The -b
option allows some deviation from this rule. For tmboot
to find executables, BEA Tuxedo system processes such as the Bulletin Board Liason (BBL) must be located in $TUXDIR/bin
. Application servers should be in the directory defined by the APPDIR
variable, as specified in the configuration file.
When booting application servers, tmboot
uses the CLOPT
, SEQUENCE
, SRVGRP
, SRVID
, and MIN
parameters from the configuration file. Application servers are booted in the order specified by the 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:
$ tmboot [-ggrpname
] [-osequence
] [-S] [-A] [-y]
Note: | For a complete list of tmboot options, see the tmboot(1) reference page. |
To boot the entire configuration, enter the following command:
prompt
>tmboot -y
tmboot
performs the following tasks:
For relatively large applications (that is, those consisting of over 50 machines), tmboot
boots entire machines in a single step rather than performing all the steps used to boot two machines in the default sequence. Following is the optimized sequence of tasks.
Note: | The boot sequence is much faster for large applications because the number of system messages is far smaller. This method generally reduces boot time by 50%. In a configuration running on a slow network, boot time can be improved by booting machines with higher speed connections to the MASTER machine first. |
Use the tmshutdown(1) command to shut down all or part of a BEA Tuxedo application. The rules for running this command are similar to those for running tmboot(1); tmshutdown
is the inverse of tmboot
.
When the entire application is shut down, tmshutdown
removes the interprocess communication (IPC) resources associated with the BEA Tuxedo system. The options used by tmboot
for partial booting (-A
, -g
, -I
, -S
, -s
, -l
, -M
, -B
) are supported in tmshutdown
. The -b
option (allowing tmboot
to be used from a non-MASTER
machine) is not supported for tmshutdown
; you must enter the tmshutdown
command from the MASTER
(or BACKUP
MASTER
) machine.
To migrate servers, use the -R
option. This option shuts down the servers without removing bulletin board entries for them. If a machine is partitioned, run tmshutdown
with the -P
LMID
option on the partitioned machine to shut down the servers on that machine.
tmshutdown
does not shut down the administrative server BBL on a machine to which clients are attached. You can use the -c
option to override this feature. You need this option for occasions when you must bring down a machine immediately and you cannot contact the clients.
You can use the -w
delay
option 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.
Only the administrator who has written the TUXCONFIG
file can execute tmshutdown(1). The application can be shut down only from the machine designated as MASTER
in the configuration file. When the BACKUP
acts as 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, an administrator can run the tmshutdown
command from a partitioned machine to shut down the application at that site.)
The order in which application servers are shut down is the reverse of the order specified by the SEQUENCE
parameter for them, or the reverse order in which they are listed 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; tmshutdown
does not remove IPC resources allocated by the DBMS.
IPC resources are operating system resources, such as message queues, shared memory, and semaphores. When a BEA Tuxedo application shuts down properly with the tmshutdown
command, all IPC resources used by the BEA Tuxedo application are removed from the system. In some cases, however, an application may fail to shut down properly and stray IPC resources may remain on the system. When this happens, it may not be possible to reboot the application.
One way to address this problem is to remove IPC resources with a script that invokes the system IPCS
command and scan for all IPC resources owned by a particular user account. However, with this method, it is difficult to distinguish among different sets of IPC resources; some may belong to a particular BEA Tuxedo application; and others to applications unrelated to the BEA Tuxedo system. It is important to be able to distinguish among these sets of resources; unintentional removal of IPC resources can severely damage an application.
The BEA Tuxedo IPC tool (that is, the tmipcrm(1) command) enables you to remove IPC resources allocated by the BEA Tuxedo system (that is, for core BEA Tuxedo and Workstation components only) in an active application.
The command to remove IPC resources, tmipcrm(1), resides in TUXDIR/bin
. This command reads the binary configuration file (TUXCONFIG
), and attaches to the bulletin board using the information in this file. tmipcrm
works only on the local server machine; it does not clean up IPC resources on remote machines in a BEA Tuxedo configuration.
To run this command, enter it as follows on the command line:
tmipcrm [-y] [-n] [TUXCONFIG_file
]
The IPC tool lists all IPC resources used by the BEA Tuxedo system and gives you the option of removing them.
Note: | This command will not work unless you have set the TUXCONFIG environment variable correctly or specified the appropriate TUXCONFIG file on the command line. |
To remove /Q IPC resources, use the qmadmin(1) ipcrm
command.