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

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

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

> HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet
> \Services\iMQ_Broker\Parameters

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

> ##### To See Logged Service Error Events

> 1. Start the Event Viewer
> 2. Look under Log > Application.
> 3. Select View > Refresh to see any error events.

> Previous Contents Index Next

> Copyright 2003 Sun Microsystems, Inc. All rights reserved.