Chapter 4 Windows Installation

This chapter explains the following topics as they apply to a Windows installation:

Hardware and Software Requirements

At a minimum, your Windows system should satisfy the requirements indicated in the following table.

Table 4-1 Hardware and Software Requirements for Windows
Component	Requirements
Operating system	Windows XP Professional SP3; Windows 2000 all editions, SP4; Windows Server 2003 Enterprise Edition
CPU	Intel Pentium 2
RAM	256 Mbytes
Disk space	The self-extracting installation file is approximately 25 Mbytes. The temporary directory used for extracting the installation files requires an additional 45 Mbytes. The installed product requires approximately 45 Mbytes. Message Queue, however, may need more space if the broker stores persistent messages locally.
Java 2 Standard Edition (J2SE)	See Table 1-1 for the supported versions of the Java Runtime Environment (JRE) and Java Software Development Kit (JDK) that are supported on Windows. The Message Queue installation program will (optionally) install the required JRE version in IMQ_HOME\jre.

Installing Message Queue on Windows

The Sun Java System Message Queue product can be downloaded from the Sun Java System website or installed from the product CD-ROM.

The following instructions explain how to install the Message Queue product either by downloading from the Sun Java System website or using the CD-ROM.

Upgrading from Previous Versions

To upgrade from prior Message Queue versions, it is recommended that you first uninstall Message Queue software as described in the Message Queue Installation Guide of the appropriate version, before installing Message Queue 3.5 SP1.

If you are upgrading from Message Queue 2.0, check the Message Queue 3.0.1 Release Notes for information about migrating any existing Message Queue 2.0 data you wish to preserve.

If you are installing Message Queue after a previous uninstall, check that any references to the previous Message Queue installation have been removed from the system’s PATH environment variable

Installed Directory Structure

The install image below reflects a full (“Typical”) Windows installation. This image might vary if you perform a partial installation.


Note	File locations for Message Queue bundled with Sun Java System Application Server, may differ from locations specified in Table 4-2.

Table 4-2 Installed Directory Structure: Windows
Windows¹	Contents
.\COPYRIGHT.TXT	Copyright text file
.\LICENSE.TXT	License text file
.\LICENSEREADME\THIRDPARTY- LICENSEREADME.TXT	License for third party software distributed by Message Queue: DOM4J, Apache Commons Logging
.\README.TXT	README text file
.\bin\ On Windows, the executable files have a .exe filename extension. This directory also includes the utility to install and uninstall the broker as a Windows Service (imqsvcadmin) as well other executables (imqbrokersvc).	Contains the executables for the broker (imqbrokerd) and the following Message Queue administration tools: Administration Console (imqadmin) Command (imqcmd) Object Manager (imqobjmgr) User Manager (imqusermgr) Database Manager (imqdbmgr) Key Tool (imqkeytool)
.\lib\	Contains files that support the Message Queue Java client runtime: /.jar jar files used to build and run Java JMS client applications /.war war files used for HTTP servlet deployment /*.rar rar files used for Message Queue resource adapter
.\lib\	Contains files used to support Message Queue tools and processes: /ext location for placing files needed for plug-in persistence capability /props subdirectory contains the broker’s default configuration files /help subdirectory contains Message Queue help files /images
.\etc\	Contains license files and instance template files.
.\var\	Working storage directory for Message Queue. /instances subdirectory which will contain configuration files, log files, access control files, flat-file user repository, and file-based persistent data stores for each broker instance
.\javadoc\	Contains the Message Queue and JMS API documentation distributed as Javadoc (HTML)
.\demo\	Source code for and instructions on how to run Java client example applications:
.\include\	Header files needed to support Message Queue C clients (Enterprise Edition only)
.\lib\	Libraries needed to support Message Queue C clients (Enterprise Edition only)²
.\demo\C\	Examples for writing C clients (Enterprise Edition only)
.\jre\	The JRE 1.4 files (on Windows only)
1. Paths are relative to IMQ_HOME (see Directory Variable Conventions). 2. See Table 1-2 for the versions of NSPR and NSS needed to support the C-API.

Installing From CD-ROM or the Web

To Install Message Queue on Windows

Quit any other programs you are running.

Download the distribution into a temporary working directory.

If you are installing from CD-ROM, insert the CD into the CD-ROM drive.

In the Windows Explorer, double-click the imq3_5-edition-win.exe file

where edition takes one of the following values: plt or ent, depending on whether you are installing the Platform Edition or Enterprise Edition, respectively.

The installation file is extracted and setup is launched. If you are installing from CD-ROM, the setup program is started automatically.

Read the license agreement. Installation and use of the product is subject to acceptance of the license agreement.

Follow the setup program’s instruction to select installation options.

Select the type of installation.

Compact Includes only the files necessary to run the broker, administration, and client applications. No documentation or example client applications are installed.

Custom Lets you specify which Message Queue modules you want to install. Your options include the broker, Java client runtime, administration tools, Message Queue resource adapter, documentation, example client applications, Java runtime, and C client runtime (Enterprise Edition).

Typical Installs all files, including broker, client runtime, administration tools, documentation, example client applications, and Java runtime.

Upgrade Platform Edition (Enterprise Only) Installs only the files necessary to enable Enterprise Edition features. This option does not overwrite the Message Queue files already installed, and does not modify the configuration of your messaging system.

Select a location for the installation.

Select or create a folder for the Windows Start > Programs menu.

Choose whether or not to install the broker as a Windows service. If you choose to install the broker as a Windows service, the broker will be started automatically at system startup and run in the background. This option requires Windows Administrator Group privileges.

If you choose not to install the broker as a Windows service now but later change your mind, you can use the imqsvcadmin utility to do so. See the Message Queue Administration Guide for information on using the imqsvcadmin utility.

Verify installation by choosing Start > Programs > Sun Java System Message Queue 3.5 >Message Broker to run the broker.

You can also compile and run example applications located in the
c:\Program Files\Sun\MessageQueue3\demo directory. See the Message Queue Java Client Developer’s Guide.

Installation Defaults

Table 4-3 Windows Installation Defaults
Installation directory	The product is installed, by default, into the following directory: C:\Program Files\Sun\MessageQueue3
Environment Variables	IMQ_HOME: The installer automatically sets the IMQ_HOME environment variable to the installation directory. IMQ_VARHOME: The IMQ_VARHOME environment variable defaults to IMQ_HOME\var. IMQ_JAVAHOME: The IMQ_JAVAHOME environment variable defaults to IMQ_HOME\jre. PATH: The installer automatically sets PATH to %PATH%;%IMQ_HOME%\bin. This enables you to run utilities, such as imqbrokerd, imqcmd, and imqobjmgr without specifying the entire path.

Troubleshooting Installation Problems

If the Message Queue installation program does not complete successfully on your Windows platform, try the following remedies. These apply regardless of whether you installed the product from CD-ROM or downloaded it from the Web.

To Troubleshoot Installation Problems on Windows

If your Windows installation of the Message Queue product is still not successful, try this more comprehensive procedure:

Upgrading from Platform to Enterprise Edition

To upgrade from the Platform Edition to the Enterprise Edition, you need to first purchase the Enterprise Edition, and then install, as described below, the Enterprise Edition license contained in the distribution, plus the C-API packages, if you wish to write C client programs. Installation of this software does not overwrite the Message Queue 3.5 SP1 modules already installed and does not modify the configuration of your Message Queue messaging system.

You can upgrade from the Platform Edition to the Enterprise Edition by installing the Enterprise Edition.

To Upgrade to Enterprise Edition on Windows

Where To Go Next

For an overview of Sun Java System Message Queue concepts, a brief introduction to writing and compiling a client application, see the Message Queue Java Client Developer’s Guide or the Message Queue C Client Developer’s Guide.

For details on configuring brokers and managing a Message Queue messaging system, see the Message Queue Administration Guide.

For class and member information used when writing a client application, browse the API documentation in the IMQ_HOME/javadoc directory.

Uninstalling Message Queue on Windows

To Remove Message Queue on Windows

Stop any running client applications.

Stop any running brokers. (You will be prompted for the admin user name and password.)

imqcmd shutdown bkr [-b hostName:port]

If you had installed the broker as a Windows service, you can stop it as follows:

From the Windows Start menu, choose Settings, then Control Panel.

Double-click the Administrative Tools icon, then the Services icon.

In the Services panel, select the Message Queue Broker entry, then click Stop.

Close the Services panel.

Unless you want to retain dynamic data, the Message Queue flat file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.

imqbrokerd -name instanceName -remove instance

Remove the Sun Java System Message Queue product by choosing Start > Programs > Sun Java System Message Queue 3.5 >Uninstall.

After Uninstall completes, remove any leftover files.

The Windows Uninstall utility does not remove files or directories created as a result of using Message Queue, such as instance configuration files or a flat-file data store.

Manually remove Message Queue references from your environment.

From the Windows Start menu, choose Settings.

In the Control Panel, double-click the System icon.

On the Environment page, select the PATH environment variable and remove the Message Queue 3.5 SP1 reference from the value.

Click Set then OK.

Previous Contents
Sun Java System Message Queue 3.5 SP1 Installation Guide