Try OpenEdge Now
skip to main content
Administration
Command and Utility Reference : WTBMAN
 

WTBMAN

Controls the operation of a configured WebSpeed Transaction Server. The utility allows you to start a Transaction Server, query its status, start and stop additional WebSpeed Agents, trim by a certain number of agents, and shut down the Transaction Server (WebSpeed only).

Syntax

Operating system
Syntax
UNIX
Windows
wtbman {
{ -name transaction-server-name
{ -kill | -start | -stop | -query
| -addagents number-to-start
| -trimagents number-to-trim|
       -listallprops |
-refresh |
-refreshStatus |
-cancelRefresh}
[ -host host-name -user user-name| -user user-name]
[ -port port-number]
}| -help }
-name transaction-server-name
Specifies the name of a Transaction Server.
-kill
Stops and removes the Transaction Server from memory, no matter what it is doing.
-start
Starts the Transaction Server.
-stop
Stops the Transaction Server.
-query
Queries the Transaction Server for its status.
-addagents number-to-start
Specifies the number of additional agents to start.
-trimagents number-to-trim
Specifies the number of additional agents to trim.
-listallprops
Displays all active broker properties, including updated values for dynamic properties that have changed.
-host host-name
Specifies the name of the machine where the AdminServer is running. If a host name is not specified, it defaults to the local host name.
-user user-name
Specifies a user name and prompts for a password when logging in to a remote machine. A user name and password are required only when you use the -host parameter and specify a remote host name. If you specify a remote host name with the -host parameter but do not specify a user name with the -user parameter, you receive a prompt for a user name and password.
-port port-number
Specifies the port number of the machine on which the AdminServer controlling the WebSpeed Transaction Server is running. If a port number is not specified, it defaults to 20931.
-help
Displays command-line help.

Example

The following table shows examples that use the wtbman command. Assume that the Transaction Server name is wsbroker1, the user name is tom, and the AdminServer is on the remote host finance at port 9999.
Table 108. WTBMAN command examples
Task
Command
Start a local Transaction Server
wtbman -name wsbroker1 -start
Start a remote Transaction Server1
wtbman -name wsbroker1 -host finance
-port 9999 -user tom -start
Query a local Transaction Server
wtbman -name wsbroker1 -query
Query a remote Transaction Server2
wtbman -name wsbroker1 -host finance
-port 9999 -user tom -query
Add agents (for example, 2) to a local Transaction Server
wtbman -name wsbroker1 -addagents 2
Add agents (for example, 2) to a remote Transaction Server3
wtbman -name wsbroker1 -host finance
-port 9999 -user tom -addagents 2
Trim agents (for example, 3) from a local Transaction Server
wtbman -name wsbroker1 -trimagents 3
Trim agents (for example, 3) from a remote Transaction Server4
wtbman -name wsbroker1 -host finance
-port 9999 -user tom -trimagents 3
Stop a local Transaction Server
wtbman -name wsbroker1 -stop
Stop a remote Transaction Server5
wtbman -name wsbroker1 -host finance
-port 9999 -user tom -stop
1 Prompts for a password.

2 Prompts for a password.

3 Prompts for a password.

4 Prompts for a password.

5 Prompts for a password.

Notes

When you specify a user name with the -user parameter, Windows supports three different formats:
*As a simple text string, such as mary, implies a local user whose user account is defined on the local server, which is the same machine that runs the AdminServer.
*As an explicit local user name, in which the user account is defined on the same machine that runs the AdminServer, except the user name explicitly references the local machine domain, for example, .\mary.
*As a user account on a specific domain. The general format is Domain\User, in which the User is a valid user account defined within the domain, and the Domain is any valid server, including the one where the AdminServer is running.
-agentdetail
Displays the procedure run by a WebSpeed agent. You can select the specific WebSpeed agent by specifying the process ID (PID) of the agent process.

Example

Use the following command to display the .r procedure run by a WebSpeed agent. It displays the port and connection state of a WebSpeed agent.
wtbman -name <name> -agentdetail <pid>
-agentkill
Stops a specific WebSpeed agent forcefully. The PID specified to the wtbman command must be an agent process for the specified WebSpeed. Use the kill command to stop a specific WebSpeed agent on UNIX. Use the taskkill command to stop a specific WebSpeed agent on Windows XP Professional Edition. This utility is not supported by the Windows Home Edition.

Example

Use the following command to stop a WebSpeed agent forcefully.
wtbman -name <name> -agentkill <pid>
-refresh
Allows the users to trim individual agents and restart new ones in order to gradually to migrate to a new version of r-code from their current version. Details of a Refresh operation are logged at a verbose level.

Example

Use the following command to refresh an AppServer.
wtbman -name <name> -refresh
-cancelRefresh
Cancels a refresh command. This command cancels a refresh operation that is running for too long. It will also stop any busy agent marked for refresh from getting trimmed automatically. The broker will not add new agents for any agent that were trimmed when the cancelled refresh operation was running. An administrator can add more agents if needed. After the refresh is cancelled, a message is returned indicating that the refresh was successful. If no refresh was active for that broker, the following message is returned:
Refresh for <brokerName> is not active

Example

Use the following command to cancel the refresh command issued for an AppServer.
wtbman -name <name> -cancelRefresh
-refreshStatus
This command returns detailed information that is captured in the following table:
Table 109. Refresh detail view output fields
Field
Value
Description
Refresh Active
Yes/No
If the refresh is not active, and if there was a refresh operation issued earlier, it shows the refreshStatus of that that operation
Refresh Start Time
yyyy-MM-dd'T'HH:mm:ss.SSS
Start time of the currently executing refresh operation. If no refresh is active, it shows the start time of the latest refresh operation that was completed
Refresh End Time
yyyy-MM-dd'T'HH:mm:ss.SSS
End time of the latest refresh operation that was completed. This is not applicable for a running refresh operation
Refresh Cancel Time
yyyy-MM-dd'T'HH:mm:ss.SSS
The time when a refresh operation was cancelled
Agents at refresh start
Integer value >= 0
Number of agents that were running at the time when refresh command was issued
Agents marked for refresh
Integer value >= 0
Number of agents that are marked to be refreshed. Agents that are busy will be marked for refresh and will be stopped only after they become available. Also the agents that were added after refresh operation started will not be refreshed. This field will be displayed for active refresh operation only.
New agents added during refresh
Integer value >= 0
No. of agents that got added after the refresh was issued. These agents won't be running old r-code, so they will not be marked for refresh
Agents at refresh cancel
Integer value >= 0
No. of agents running at the time of refresh cancellation
Agents refreshed
Integer value >= 0
It shows the actual number of agents refreshed for a refresh operation that is complete
Refresh operation count
Integer value >= 0
No. of times a refresh operation is invoked including the currently executing refresh operation since start of the broker
Refresh cancel count
Integer value >= 0
No. of times a refresh cancellation was is invoked since start of the broker
PID of agents marked for refresh
Integer value >= 0
Number of agents added after the refresh was issued. This doesn't include the agents that were started as replacement agents. This include agents added due to addservers or new client requests.
PID of agents refreshed
Integer value >= 0
List the PID of agents that were Refreshed(replaced by new agents)..

Example

Use the following command to query the status of a refresh command issued for an AppServer.
wtbman -name <name> -refreshStatus