This chapter describes how to start up and shut down Tmax system in various environments.
After configuring the configuration file, the administrator can start up the Tmax system. Once Tmax is running, it is rarely shut down except for when an external fatal error, such as a hardware or OS failure, occurs. However, the administrator will need to shut down and restart the system when the configuration file must be modified or recreated, or when the system was unexpectedly terminated due to external reasons.
The basic configuration of the Tmax system must be complete before attempting to start up the system. Run through the following checklist prior to starting up the system.
Does the Tmax configuration binary file exist?
Do Tmax executables (TMM, CLL, CLH, and TMS, etc.) exist in the directory specified in the TMAXDIR item of the NODE section?
Can the server programs, registered within the SERVER section of the configuration file, be found in the directory specified in the APPDIR item of the NODE section?
Is racd running on each node to enable centralized management?
In general, a Tmax system is made up of multiple nodes in a single domain. This type of system usually requires a centralized management system. If racd (remote access control demon) is installed on each node in advance, it is possible to manage the entire Tmax system from a single node. A single command can be issued through racd to compile the configuration file, start or shut down the Tmax system, or dynamically modify the configuration file.
In order to load racd, TMAX_RAC_PORT must be defined through an environment variable. The system can start up without referencing the environment variables in the Tmax configuration file by specifying the port number of the racd, which is used for centralized management, and starting up racd by executing "racd – k".
The racd command centralizes the management of nodes in a distributed multi-node environment. racd is a daemon process that starts in each node to allow a single node to manage a Tmax system built with multiple nodes in a domain. The node that manages a Tmax system is not required to execute a racd.
racd allows a node in a domain to manage all nodes with a tmadmin or a configuration file, which is applied to all nodes in a domain by a cfl.
If IPv6 is used, the following must be specified in a configuration file.
SYSTEM_IPV6=Y
To use a [-k] option, the following must be specified in an environment variable.
TMAX_RAC_IPV6=Y
Usage
$ racd [-d] [-f binary Tmax configuration file name] [-h] [-k] [-i filename] [-l Label] [-P umask] [-V]
| Option | Description |
|---|---|
| [ -d ] | Works in the debug mode. |
| [ -f binary Tmax configuration file name ] | A binary Tmax configuration file to be used. The binary configuration file is the result of executing a cfl command and is referenced by tmboot and tmdown. The path to the file can also be specified. If a path is not specified, <tmconfig> in the $TMAXDIR/config directory will be used. |
| [ -h ] | Shows command Help. |
| [ -k ] | Option to use a binary Tmax configuration file. If this option is specified, the configuration file will not be used. A racd is usually executed with this option (passive listen mode). If this option is used when IPv6 is used, 'TMAX_RAC_IPV6=Y' must be set because the configuration file will not be used. |
| [ -i filename ] | Used to define multiple logical nodes in a single physical machine. If the NODETYPE of a logical node is SHM_RACD, a racd must be executed for each logical node and each node must have a unique RACPORT. A TMAX_RAC_PORT environment variable must be set before executing a racd. When there are too many logical nodes, the name of the file that defines TMAXHOME, TMAXDIR, and TMAX_RAC_PORT can be specified, because it is difficult to set the variable for each node. For more information, see the examples in the following sections. |
| [ -l Label ] | A delimiter used for information registered in a configuration file. When information of two or more systems is registered in a single file, the delimiter separates the information of each system. |
| [ -P umask ] | Allows a user to create a file with desired permissions for a process started by a racd. |
| [ -V ] | Shows the version of an executable file. |
Environment
This command can be used in a system with a Tmax system installed.
Examples
The following sets a desired umask by specifying a -P option to a racd.
<tmax.racd>
[tmaxs1] TMAXHOME = /user2/starbj81/tmax32 TMAXDIR = /user2/starbj81/tmax32 TMAX_RAC_PORT = 3333 [NODE1] TMAXHOME = /user2/starbj81/tmax32 TMAXDIR = /user2/starbj81/proj1 TMAX_RAC_PORT = 4335 [NODE2] TMAXHOME = /user2/starbj81/tmax32 TMAXDIR = /user2/starbj81/proj2 TMAX_RAC_PORT = 4337
Create a configuration file.
*DOMAIN
tmax1 SHMKEY = @SHMEMKY@, MINCLH = 1, MAXCLH = 3,
TPORTNO = @TPORTNO@, BLOCKTIME = 30, RACPORT = 3255
*NODE
@HOSTNAME@ TMAXDIR = "@TMAXDIR@",
APPDIR = "@TMAXDIR@/appbin",
PATHDIR = "@TMAXDIR@/path",
@RMTNAME@ TMAXDIR = "@RMTDIR@",
APPDIR = "@RMTDIR@/appbin",
PATHDIR = "@RMTDIR@/path",
*SVRGROUP
svg1 NODENAME = "@HOSTNAME@", COUSIN = "svg2"
svg2 NODENAME = "@RMTNAME@"
*SERVER
svr2 SVGNAME = svg1, CLOPT = "-o $(SVR).out -e $(SVR).err"
*SERVICE
TOUPPER SVRNAME = svr2
Start a racd in a remote node.
$ export TMAX_RAC_PORT = 3255 $ racd –k –P 055
Start all Tmax instances in a HOST node (tmboot).
Check the permission for the <svr2.out> file in the ULOGDIR of the RMT node.
The following executes a racd in NODE 1.
$ racd -k -i tmax.racd -l NODE1
The following uses only information used by another command, such as tmboot, without referring to a configuration file.
$ racd -k
1. For more information about tmboot and tmdown, refer to "4.1.2. tmboot" and "4.2.1. tmdown" respectively.
2. For more information about logical node settings, refer to HOSTNAME in the "3.2.2. NODE Section" of the "Tmax Administrator's Guide".
The tmboot command starts a Tmax system (or a portion of it) using a Tmax configuration file. When this command is executed without an option or only with a [-f] option, all Tmax management processes and all server processes registered in the SERVER section of a Tmax configuration file are executed.
Tmax management processes are executed in all nodes registered in a NODE section. The execution order is TMM, CLL, and finally CLH. If an OPENINFO is registered in the SVRGROUP section in a server group, TMS processes are executed by referring to TMSNANE and MINTMS for each server group. Tmax management processes are executed in the bin directory under a TMAXDIR directory defined by each node.
After Tmax management processes are created, all application server processes in a SERVER section are executed. The application server processes are executed in the order they were registered in a section. The tmboot command initializes the server processes with tpsvrinit() and then executes them after they are initialized. The number of application server processes executed by a tmboot command is defined by a MIN value. If MIN is not specified, the default value will be 1.
The tmboot command uses CLOPT, MIN, and MAX values for servers in a SERVER section. These values are the boot parameters used by a tmboot when starting a server process. Other items are runtime parameters used by a system after a server starts. For more information about how to set parameters, refer to the SERVER section in a source configuration file.
All application server processes are executed from a APPDIR directory defined for a running node:
Usage
$tmboot [-A] [-b] [-c]
[-f binary Tmax configuration file name]
[-g servergroup_name [-a] [-i]]
[-h] [-V] [-n node_name]
[ -o clopt_string ]
[-q RQ svg_name]
[-s server_name [-k count] [-a]]
[-S server_name [-a]]
[-t TMS_name[-k all]]
[-B TRB_node] [-T] [-w]
[-d boot_time] [-D]
[-e clh | cas | tlm ]
[-k] [-R] | Option | Description |
|---|---|
| [ -A ] | Executes all application server processes defined in the SERVER section of a Tmax configuration file. |
| [ -b ] | Used to arbitrarily start a server process specified as a backup. |
| [ -c ] | Executes an additional CLH process. The number of CLH processes cannot exceed a MAXCLH value, which is defined in a Tmax configuration file. |
| [ -f binary Tmax configuration file name ] | A binary Tmax configuration file (the result of compiling a source file with a cfl), which is specified with a path. If a [-f] option is not specified, <tmconfig> in a config directory under a TMAXDIR is used by default. |
[-g servergroup_name [-a] [-i]] | Executes a server process in a specified server group. The server group name is registered in the SVRGROUP section of a Tmax configuration file. If a [-a] option is also used, a TMM process, not a TMBOOT process, will start a server. If an [-i] option is not used, a server booting process will be stopped if a server reaches the maximum number of times it can be restarted. However, if an [-i] option is used, even if a server reaches the maximum number of times it can be restarted., a following server will be started and the entire process will proceed. If all servers reach the maximum number of times it can be restarted., the following message will be displayed. (I) BOOT3022 all servers in group (svgname) reached max [BOOT0039] |
| [ -h ] | Shows command Help. |
| [ -V ] | Shows the version of an executable file. |
| [ -n node_name ] | Executes a server process in a specified node. The node name must be previously registered in the NODE section of a Tmax configuration file. |
| [ -o clopt_string ] | Adds a CLOPT string. |
| [ -q RQ svg_name ] | Starts a RQS. |
| [ -s server_name [-k count] [-a] ] | Executes a specified server processes. The server processes must be previously registered in the SERVER section of a Tmax configuration file. To specify the number of server processes, use a [-k] option. The number of server processes, which includes currently running server processes, cannot exceed the value of MAX in the SERVER section. If a [-k] option is omitted, only a specified server process will be executed. If an -a option is used, a TMM process, not a TMBOOT process, will start a server. |
| [ -S server_name ] | Executes a MIN number of server processes. If an [-a] option used, a TMM process, not a TMBOOT process, will start a server. |
| [ -t TMS_name [-k all] ] | Executes an additional specified TMS process. The number of TMS processes cannot exceed a MAXTMX value defined in a Tmax configuration file. [-k all] enables transaction recovery. Because recovery is executed when all groups are terminated and then restarted, recovery is performed by each TMS group. To start and terminate all TMSs with a specific name, use this option. |
| [ -B TRB node ] | Starts a TRB node. |
| [ -T ] | Executes only TMM, CLL, CLH, and TMS processes. |
| [ -w ] | Option to start processes sequentially. If no option is used for a tmboot command, all registered server processes will start at the same time. Some server processes may not start normally because certain OSs cannot create sufficient resources.
|
| [ -d boot_time ] | Starting multiple server processes simultaneously can cause a problem because a CLH can overload with registration requests. To solve this problem, this option allows a registration interval to be adjusted by specifying the period spent to start server processes. (Default value: LOCK and NO-WAIT, unit: usec)
|
| [ -D ] | Similar to a [-d] option, but for a FINITE-WAIT, a server will unconditionally WAIT until a time specified in a |VAL|, even if a signal is received from a server process. |
| [ -e clh | cas | tlm ] | Starts CLH, CAS, and/or TLM Tmax engine processes. This option is used when an error occurred while using a tmboot command or when an engine process is terminated by a kill command. The tmdown command does not support this option.
|
| [ -R ] | Starts a Tmax system in a remote node using a remote shell (rsh or remsh). |
Environment
This command can be used in a system with a Tmax system installed.
Examples
The following executes all Tmax processes and application server processes by referring to a <tmconfig> file in a config directory under a TMAXDIR directory:
$ tmboot
The following starts all TMS created with tms_name:
$ tmboot -t tms_name -k all
In the following, a configuration option of a server group is used. When several server groups use the same tms_name, the name of a server group that includes a corresponding TMS can be specified with a [-g] option. If a name is not specified, the TMS of a first server group with a specified name is started.
$ tmboot -t tms_name -k all -g svgname
The following executes all application server processes defined in a SERVER section by referring to a <tmconfig> file:
$ tmboot -A
The following executes application server processes in a cosmo node registered in a NODE section by referring to a <exconfig> configuration file in a /user1/tmax/con directory:
$ tmboot -n cosmo -f /user1/tmax/con/exconfig
The following executes five svr1 processes by referring to a <tmconfig2> configuration file:
$ tmboot -s svr1 -k 5 -f tmconfig2
For more information about the cfl and tmdown commands, refer to Tmax. cfl and "4.2.1. tmdown".
When a tmboot command is used to boot Tmax, a <tmconfig> binary configuration file in '$TMAXDIR/config/ is copied to $TMAXDIR/path/ and a configuration file under a $TMAXDIR/path is used. However, if $TMAXDIR/config/tmconfig is referenced to start a specific server with -S or -s options and a Tmax engine is already started, a problem can arise in the environment.
Configuration File
<Original Configuration File>
*SVRGROUP svg1 NODENAME = "tmaxh4" *SERVER svr1 SVGNAME = svg1 svr2 SVGNAME = svg1 *SERVICE TOUPPER1 SVRNAME = svr1 TOUPPER2 SVRNAME = svr2
<Changed Configuration File during System Operation>
*SVRGROUP svg1 NODENAME = "tmaxh4" *SERVER svr1 SVGNAME = svg1 svr3 SVGNAME = svg1 svr2 SVGNAME = svg1 *SERVICE TOUPPER1 SVRNAME = svr1 TOUPPER3 SVRNAME = svr3 TOUPPER2 SVRNAME = svr2
Use CFL to recompile a configuration file that was changed during system operation.
$ cfl –i node1.m
Start a newly added server.
$ tmboot –S svr3
If tmboot -S is used after changing a configuration during runtime, the following error can occur.
(E) BOOT3007 maxsvr (1) is over for svr(svr3:svr2): nodeno = 0, svri = 5, cur = 1, ksvr = 1 [BOOT0015]
When CFL is used in an operating environment, changes are reflected in $TMAXDIR/config/tmconfig but actual shared memory is specified as defined in $TMAXDIR/path/tmconfig. If a newly added server process using tmboot -S is booted, a server process that is already running can be restarted, which can result in a problem. The CFL command is not allowed when a Tmax engine has been started. If CFL is used, the resulting error can cause a critical problem in the system operation and hinder debugging.
The path to a <tmconfig> file referenced when booting each server with a tmboot command with [–S], [-s], [–g], [-q], [-t], and [-A] options during the operation of a Tmax engine does not use $TMAXDIR/config/tmconfig but instead uses $TMAXDIR/path/tmconfig. However, $TMAXDIR/path/tmconfig is referenced when starting the engine.
$ cfl –i new_config.m –o tmchg $ tmadmin : cfgadd –I tmchg $ tmboot –S new_svr –f tmchg
When executing a tmboot, if a specific binary configuration file is designated using a [-f] option, $TMAXDIR/config/tmconfig will be used to start a server. To dynamically add a server, a specific configuration file must be designated by using a [–f] option. The server is then started by using the changed binary configuration file placed in $TMAXDIR/config/.
The Tmax binary configuration file is used to shut down Tmax system. During the shutdown process, shared memory, which was used by the system, is cleared, and all running Tmax processes (TMM, TMS, CLL, CLH, RQS) and application programs are terminated.
The tmdown command shuts down a Tmax system (or a portion of it). tmdown shuts down a Tmax system by referring to a Tmax configuration file, while a binary Tmax configuration file (a result of compiling 'srcconfig' with 'cfl ': See cfl) must be specified with a path by using a [-f] option.
If a [-f] option is not specified, the <tmconfig> file in a TMAXDIR/config directory will be used by default. If only a [-f] option is used, tmdown will end all Tmax management processes and all server processes registered in the SERVER section of a Tmax configuration file and will remove IPC resources related to a Tmax system. The following is the termination order:
Application server processes registered in the SERVER section are ended.
Any active TMS process in each server group is terminated.
Tmax management processes are terminated: first CLH, second CLL, and then TMM. However, if the MIN value of CLH is not 1, CLL may be terminated before CLH.
It is assumed that a service is dynamically registered in a server and the service is removed from the shared memory because the server is shut down. In this case, if fault tolerance is activated, a naming service cannot be provided for clients that accessed a backup node. (All backup servers are terminated and servers running on normal nodes are restarted.) Therefore, dynamic services of backup servers should not be deleted from shared memory even after a server is shut down.
Usage
$tmdown [-A] [-f binary Tmax configuration file name] [-g servergroup_name] [-h] [-V][-i] [-n node_name] [-p server_num] [-q RQ svg_name] [-s server_name [-k count]] [-S server_name] [-t TMS_name[-k all]] [-w wait_time] [-B Nodename][-R] [-y]
| Option | Description |
|---|---|
| [ -A ] | Terminates all application server processes. |
| [ -f binary Tmax configuration file name ] | A binary Tmax configuration file referred to when shutting down a system. If a file name is not specified, <tmconfig> in the $TMAXDIR/config directory will be used by default. |
| [ -g servergroup_name ] | Terminates all server processes of a specified server group. |
| [ -h ] | Shows command line help. |
| [ -V ] | Shows the version of an executable file. |
| [ -i ] | Immediately executes the tmdown command. Without an [-i] option, the tmdown command is executed after all current operations are complete. With this option, all processes are unconditionally terminated and tmdown is executed. Use this option carefully. |
| [ -n node_name ] | Ends server processes of a specific node. The node name must be pre-registered in the NODE section of a Tmax configuration file. |
| [ -p server_num ] | Ends a specified server process. Unlike a [-s] option, this option ends a specific process using a process number (spr_no), which can be displayed with a "st -p" command through tmadmin. |
| [ -q RQ svg_name ] | Terminates a RQS. |
| [ -s server_name [-k count]] | Ends only specified server processes. The server process names must be pre-registered in the SERVER section of a Tmax configuration file. Multiple server processes can be terminated by this option by using a [-k] option to specify the number of server processes. If the number specified in the [-k] option is greater than the number of actual server processes, all processes will be terminated and an error will not occur. If the [-k] option is not used, only a single server process will be terminated. |
| [ -S server_name] | Terminates all specified server processes. |
| [ -t TMS_name [ -k all ]] | Terminates only a specified TMS process. [ -k all ] activates the Transaction Recovery feature. Recovery is performed in a TMS Group unit. This option is used to boot/terminate all TMS that have a specific name. |
| [ -w wait_time ] | Begins tmdown after wait_time seconds. |
| [ -B Nodename ] | Terminates a TRB node. |
| [ -R ] | Used for rolling down. |
| [ -y ] | Terminates a Tmax system without asking whether or not to terminate (y | n). |
Examples
The following is an example of shutting down an entire Tmax system by referring to a <tmconfig> file in the TMAXDIR/config directory. Tmax management processes and application processes are all terminated.
$ tmdown
The following is an example of shutting down all TMSs named tsm_name.
$ tmdown -t tms_name -k all
The following is an example of using a server group configuration option. If multiple server groups have the same tms_name, use a [–g] option to specify the name of the server group to which the TMS belongs.
If a server group name is not specified, the first server group with a matching TSM name will be terminated.
$ tmdown -t tms_name -k all -g svgname
The following is an example of shutting down an entire Tmax system by referring to a <tmconfig2> file.
$ tmdown -f tmconfig2
The following is an example of terminating all application server processes in a svr1 by referring to a <tmconfig> file.
$ tmdown -S svr1
The following is an example of forcibly terminating application server processes in a svr1 by referring to a <tmconfig> file. Any server process not terminated immediately can be terminated by using a [-i] option.
$ tmdown -S svr1 -i
The following is an example of forcibly terminating a server process using a <spr_no> by referring to a <tmconfig> file. When there are multiple server processes in a server, only the server process of a server that is in a loop can be forcibly terminated.
$ tmdown -k <spr_no> -i
The following is an example of terminating all application server processes in a 'cosmo' node registered in a NODE section by referring to a <exconfig> file in a '/user1/tmax/con' directory.
$ tmdown -n cosmo -f /user1/tmax/con/exconfig
The following is an example of terminating only one active svr1 process by referring to a <tmconfig2> file.
$ tmdown -s svr1 -f tmconfig2
In previous versions of Tmax, when a Tmax system was abnormally terminated while processing client requests, requests being processed were completed but enqueued requests would fail, and an error message was reported. However, Tmax 5 provides the Rolling Down function, which allows a server to reply to all requests (including enqueued requests) before the server terminates.
Usage
$ tmdown –R –n node_name
| Option | Description |
|---|---|
| –n node_name | A node to be terminated. |
Environment
This command can be used in a system with a Tmax system installed.
Example
Assume that NODE A and NODE B are part of a multi-node (or multi-domain) system and a total of 100 clients are currently accessing NODE A.
When terminating the Tmax system of NODE A:
$ tmdown –R –n NODEA
A CLL in NODE A blocks a listening port for a client.
A Tmax system in NODE A finishes processing requests currently being handled by a server and then sends the results to the client.
The Tmax system in NODE A sends enqueued requests to NODE B, which is set as TMAX_BACKUP_ADDR.
The Tmax system in NODE A is shut down.
A Tmax system in NODE B handles the requests received from NODE A and directly replies to the client.
All clients connected to NODE A get the normal reply.
When terminating Tmax system of NODE B:
$ tmdown –R –n NODEB
A CLH in NODE A distributes 100 clients requests to NODE A and NODE B equally.
Enter tmdown -R –n NODEB to terminate the Tmax system in NODE B.
A CLL in NODE B blocks a listening port for a client.
The Tmax system in NODE B finishes processing requests currently being handled.
Because the client is connected to NODE A, the Tmax system in NODE B sends the processing results to CLH in NODE A. CLH in NODE A replies to each client.
The Tmax system in NODE B sends enqueued requests to NODE A, which is specified as TMAX_BACKUP_ADDR.
The Tmax system in NODE B is shut down.
The Tmax system in NODE A processes the requests and replies to each client.
All clients connected to NODE A get a normal reply. All 100 clients must get a normal reply.
For NODE B to process client requests instead of NODE A, TMAX_BACKUP_ADDR and TMAX_BACKUP_PORT of the client connected to NODE A must be specified to that of NODE B. Otherwise, when the Tmax system in NODE A is shut down, the enqueued client requests fail and the TPESYSTEM error is reported.