Appendix D Using a Broker as a Windows Service

This 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 Service

You have the option of installing a broker as a Windows service when you install Message Queue. You can also use imqsvcadmin to install a broker as a Windows service after you have installed Message Queue.

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.

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

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 Subcommands

The Message Queue Service Administrator utility (imqsvcadmin) includes the subcommands listed in Table D-1:

Table D-1 imqsvcadmin Subcommands
Subcommand	Description
install	Installs the service and specifies startup options.
query	Displays the startup options to the imqsvcadmin command. This includes whether the service is started manually or automatically, its location, the location of the java runtime, and the value of the arguments passed to the broker on startup.
remove	Removes the service.

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 Message Queue. 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

Removing 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.


imqsvcadmin -query

Service iMQ_Broker is installed.
Display Name: iMQ_Broker
Start Type: Manual
Binary location: c:\Program Files\Sun Microsystems\ Message Queue 3.5\bin\imqbrokersvc
JavaHome: c:\j2sdk1.4.0
Broker Args: -passfile d:\imqpassfile

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.

Previous Contents Index Next
Sun Java System Message Queue 3.5 SP1 Administration Guide