Sun ONE Message Queue 3.5 Administrator's Guide |
Appendix D
Using a Broker as a Windows ServiceThis appendix explains how you use the Service Administrator (imqsvcadmin) utility to install, query, and remove a broker running as a Windows Service.
Running a Broker as a Windows ServiceYou have the option of installing a broker as a Windows service when you install Sun ONE Message Queue. You can also use imqsvcadmin to install a broker as a Windows service after you have installed MQ.
Installing a broker as a Windows service means that it will start at system startup time and run in the background until you shut down. Consequently, you do not use the imqbrokerd command to start the broker—unless, you want to start an additional instance. To pass any start-up options to the broker, you can use the -args argument to the imqsvcadmin command (see Table D-2) and specify exactly the same options you would have used for the imqbrokerd command (see "Starting a Broker"). Use the imqcmd command to control broker operations as usual.
When running as a Windows service, the Task Manager lists the broker as two executable processes. The first is imqbrokersvc.exe, which is the native Windows service wrapper. The second is the Java runtime that is actually running the broker.
Only one broker at a time can be installed and run as a Windows service.
Service Administrator Utility (imqsvcadmin)The Service Administrator utility (imqsvcadmin) allows you to install, query, and remove the broker (running as a Windows service). This section describes the basic syntax of imqsvcadmin commands, provides a listing of subcommands, summarizes imqsvcadmin command options, and explains how to use these commands to accomplish specific tasks.
Syntax of the imqsvcadmin Command
The general syntax of imqsvcadmin commands is as follows:
imqsvcadmin subcommand [options]
imqsvcadmin -h
Note that if you specify the -v, -h, or -H options, no other subcommands specified on the command line are executed. For example, if you enter the following command, help information is displayed but the query subcommand is not executed.
imqsvcadmin query -h
imqsvcadmin Subcommands
The MQ Service Administrator utility (imqsvcadmin) includes the subcommands listed in Table D-1:
Summary of imqsvcadmin Options
Table D-2 lists the options to the imqsvcadmin command. For a discussion of their use, see the task-based sections that follow.
Table D-2 imqsvcadmin Options
Option
Description
-h
Displays usage help. Nothing else on the command line is executed.
-javahome path
Specifies the path to an alternate Java 2 compatible runtime to use (default is to use the runtime on the system or the runtime bundled with MQ.
Example: imqsvcadmin -install -javahome d:\jdk1.4
-jrehome path
Specifies the path to a Java 2 compatible JRE.
Example: imqsvcadmin -install -jrehome d:\jre\1.4
-vmargs arg [[arg]…]
Specifies additional arguments to pass to the Java VM that is running the broker service. (You can also specify these arguments in the Windows Services Control Panel Startup Parameters field.)
Example: -vmargs "-Xms16m -Xmx128m"
-args arg [[arg]…]
Specifies additional command line arguments to pass to the broker service. For a description of the imqbrokerd options, see "Starting a Broker".
(You can also specify these arguments in the Windows Services Control Panel Startup Parameters field.) For example,
imqsvcadmin -install
-args “-passfile d:\imqpassfile”
The information that you specify using the -javahome, -vmargs, and -args options is stored in the Window’s registry under the keys JavaHome, JVMArgs, and ServiceArgs in the path
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet
\Services\iMQ_Broker\ParametersRemoving the Broker Service
Before you remove the broker service, you should use the imqcmd shutdown bkr command to shut down the broker. Then use the imqsvcadmin remove command to remove the service, and restart your computer.
Reconfiguring the Broker Service
To reconfigure the service, remove the service first, and then reinstall it, specifying different startup options with the -args argument.
Using an Alternate Java Runtime
You can use either the -javahome or -jrehome options to specify the location of an alternate java runtime. You can also specify these options in the Windows Services Control Panel Startup Parameters field. Note that the Startup Parameters field treats the back slash (\) as an escape character, so you will have to type it twice when using it as a path delimiter; for example, -javahome d:\\jdk1.3.
Querying the Broker Service
To determine the startup options for the broker service, use the -q option to the imqsvcadmin command.
Troubleshooting
If you get an error when you try and start the service, you can see error events that were logged by doing the following.
To See Logged Service Error Events