View source for MIRC Installation on Vista

This article describes how to install MIRC on a Vista system. The procedure is a little different from that for XP because Vista requires privileges to be elevated before certain functions can be performed. Two methods of installation are described. The first allows Tomcat to be run as a Windows service. This is the recommended approach. The second requires that Tomcat be started and stopped manually. 

In all these instructions, it is assumed that you are logged in as an administrator and that User Account Control (UAC) is turned on. When UAC is turned on, an administrator is prompted whenever a program requires administrative privileges. This is the most restrictive mode, and most systems operate in this way.

==Installing Tomcat as a Windows Service under Vista and Windows 7==
===Install Java===
When Tomcat is run as a Windows service, it requires only the Java Runtime Environment (JRE), not the Java Developer's Kit (JDK). Download the latest Java Standard Edition JRE for Windows from http://java.sun.com/javase/downloads/index.jsp. At this writing, the latest Java is version 1.6. Be sure to select the correct JRE for your Windows platform (Windows, Windows Intel Itanium, or Windows x64). 

Run the file. The installer will provide a page for selecting which components to install. It is safe to accept the defaults, but you can save space by deselecting the documentation and the source code. The other components in the selection list are required.

===Install the JAI ImageIO Tools===
Download the latest release of the Java Advanced Imaging (JAI) ImageIO Tools for the JRE from http://java.sun.com/products/java-media/jai/downloads/download-iio-1_0_01.html. Select the <b>JRE Install</b> version. It will have a name like <b>jai_imageio-1_1-lib-windows-i586-jre.exe</b>. (There is no special version for 64-bit systems.) Note that the ImageIO Tools are separate from the JAI, so be careful to obtain the ImageIO Tools, not the full JAI. The JAI itself is <b>not</b> required.

Run the file and accept all the defaults.

===Install Tomcat===
MIRC now runs on both Tomcat 5.5 and Tomcat 6.0.

Download the latest Tomcat 6 Core Windows Service Installer from http://tomcat.apache.org/download-60.cgi.

<b>IMPORTANT:</b> Please follow these instructions very carefully. (Trust me, you don't want the trouble we went through to discover all this.)

<b>Turn off</b> any antivirus software you may have running on your system, <em>even if you don't think it is necessary</em>. 

<b>Right-click</b> the Windows Service Installer and select <b>Run as administrator</b>. The program will start and display a welcome screen. Click <b>Next</b>.

On the license agreement page, accept the terms.

The installer will next display the component selection page shown below. First, click the plus sign beside <b>Tomcat</b> to expand it into its three subcomponents, Core, Service, and Native. Make sure that Tomcat and all three subcomponents are checked. (Core is not selectable, but it should already be checked.) Then, uncheck the remaining components and click '''Next'''.


[[Image:InstallTomcat3_base.jpeg |center]]


<b>IMPORTANT:</b> The program will next display the install location page. The default location is in <b>Program Files</b>. Do <b>not</b> install Tomcat in this location. On Windows 7 installations, problems have been reported when installing MIRC on a Tomcat located in <b>Program Files</b> (or in <b>C:\users</b>). Instead, click <b>Browse</b> and navigate to a new directory. Here are two considerations:

*It is generally best to install Tomcat in the root of a drive or partition because that makes it easier for the MIRC installer to find Tomcat during an upgrade. 
*If you have multiple disk drives on your system, or multiple partitions (C, D, E, ...) on your drive, you should install Tomcat on a partition that has lots of free space. All the documents and images that you will store on your MIRC site will be stored within the Tomcat folder, so you should put Tomcat where there is as much room as possible. 

When you're happy with the installation directory location, click '''Next'''.

The installer will then display the page shown below, allowing you to select the port on which the server will listen for connections. The default Tomcat port is 8080. If you don’t have any other web servers running on your computer, you could decide to run on the default port for the world wide web, which is 80, but generally it is fine to stay with 8080.  This page also allows you to define the administrator's username and password. You should choose something you can remember. After you make whatever selections you want, click '''Next'''.


[[Image:InstallTomcat6_base.jpeg|center]]


Next, the installer will find the Java JRE. Click <b>Install</b>, and the process will proceed to the end. When the final page is displayed, <u>un</u>check the two checkboxes and click the <b>Finish</b> button.

At this point, re-enable the antivirus software.

===Remove the Apache Tomcat Monitor from the Startup List===
When Tomcat is installed as a Windows service, the Apache Tomcat Monitor, called <b>Tomcat6w.exe</b>, is placed in the <b>Tomcat/bin</b> directory and configured to run when Vista starts. This program requires administrative privileges to allow it to access the Tomcat service, and there is no way to give it administrative privileges automatically on startup, so it will fail when run in this way. To disable the Apache Tomcat Monitor on startup, click the <b>Start</b> button in the task bar, enter <b>msconfig</b> in the text field, and press the <b>Enter</b> key.

The <b>System Configuration</b> window will appear. Click the <b>Startup</b> tab, look for an item called <b>Apache Tomcat Monitor</b> or <b>Procrun Service Manager</b>, and <u>un</u>check it. Then click <b>OK</b>. The program may ask to restart the machine; if it does, do it.

===Configure the Tomcat Memory Pool===
The standard Tomcat memory pool is not large enough for handling large medical images. To configure the memory pool, start the Apache Tomcat Monitor. Click the <b>Start</b> button in the task bar. <b>Right-click</b> the item called "Monitor Tomcat" and select <b>Run as administrator</b>. If you don't see the menu item, then look for <b>Tomcat5w.exe</b> in the <b>Tomcat\bin</b> directory, <b>right-click</b> it and select <b>Run as administrator</b>. This will launch the monitor and put an icon called "Apache Tomcat" in the system tray (the collection of icons at the right end of the task bar).

Click the <b>Java</b> tab. You will see a window like this:


[[Image:Service4.JPG|center]]


The values shown in the picture above, 128 and 256, should be large enough for most applications, but if you plan to have more than 1000 documents on your system, use 256 and 512 instead. These parameters can be changed at any time as the site grows. After setting the memory allocation parameters, click '''OK'''.

To access the Apache Tomcat Monitor again, you can double-click the icon in the system tray, or right-click it and select <b>Configure</b>.

===Starting and Stopping the Apache Tomcat Service===
To start or stop the Apache Tomcat service, you must use the Windows Services applet, which can be found by clicking the <b>Start</b> button and typing <b>Services</b>. Alternatively, it can be found by opening the Control Panel, selecting <b>Classic View</b>, and double-clicking <b>Administrative Tools</b>. To run the applet, right-click the <b>Services</b> line in the right pane and select <b>Run as administrator</b>. (You may want to put a short-cut to the Services applet somewhere more convenient.)

Note: Although the Apache Tomcat Monitor also provides buttons and menu selections for starting and stopping tomcat, it appears that the ones which stop Tomcat do not work. The Windows Services applet always works.

===Common Problems===
Certain problems have occurred often during installations around the world.
====C Runtime Library====
When Tomcat runs as a Windows service, it requires the C Runtime Library to be present. This is a file called <b>msvcr71.dll</b>. If Tomcat fails to start and the Tomcat/logs directory doesn't indicate another problem, the simplest thing to do is place a <u>copy</u> of the file in the <b>Tomcat\bin</b> directory. The file can usually be found in the <b>C:\Windows\System32</b> directory or the Java <b>jre\bin</b> directory.
Do <u>not</u> remove the file from where you found it.

====Port 8005====
On some systems, problems starting Tomcat have occurred where the logs in Tomcat/logs report that port 8005 is already in use. (It has been reported, but not confirmed, that certain commercial music applications use that port.) By default, Tomcat listens for shutdown commands on port 8005, and if it cannot obtain the port, it refuses to start. If this problem occurs, the simplest solution is to edit the <b><tt>Tomcat/conf/server.xml</tt></b> file with a text editor like Notepad. Search for <b><tt>8005</tt></b>. It only occurs once in the file. Change it to <b><tt>8006</tt></b>. Then start Tomcat.

====Encoding CP1252====
After installation of MIRC, there have been problems starting Tomcat where Tomcat reports in the logs that it finds an encoding called CP1252. The error looks like this:
<tt>
:org.apache.tomcat.util.digester.Digester fatalError
:SEVERE: Parse Fatal Error at line 1 column 40: Invalid encoding name "cp1252".
</tt>
If that occurs, the simplest solution is to edit the <b><tt>Tomcat/conf/tomcat-users.xml</tt></b> file and remove <b><tt>encoding="cp1252"</tt></b> from the first line of the file. (Alternatively, you could just change <b><tt>cp1252</tt></b> to <b><tt>utf-8</tt></b>.) Then start Tomcat.

Starting with MIRC T35delta, the MIRC installer detects and fixes this problem automatically, so it should not occur again.

====JAI ImageIO Tools====
During the operation of MIRC, if you find that you cannot insert images into a file cabinet or a document, look in the Tomcat/logs. Look for an error like:

:<b><tt>java.lang.NoClassDefFoundError: com/sun/media/imageio/stream/StreamSegmentMapper</tt></b>

The StreamSegmentMapper is part of the ImageIO Tools, and the error means that Java can't find the class.

This can happen if either the JAI ImageIO Tools were not installed or if the server has multiple Javas installed and the tools were installed on a different Java from the one that Tomcat is running. (It might also happen if the tools were already installed and you ran the installer for the tools again, in which case the installer would remove the tools, and if you weren't paying close attention, you might not have noticed.)

You can figure out what Java you are running by starting the Apache Tomcat Properties applet as described in section 1.5 above. Click the Java tab and look at the Java Virtual Machine field. It will be something like:

:<b><tt>C:\Program Files\Java\jre6\bin\client\jvm.dll</tt></b>.

To find whether the tools have been installed, look in the <b><tt>jre6/lib/ext</tt></b> directory for these two files:

*clibwrapper_jiio.jar
*jai_imageio.jar

If they are present, you have the tools. If not, you don't. You can install the ImageIO Tools at any time, even after you have installed MIRC. See section 1.2 above for instructions.

==Installing Tomcat <font color="red">NOT</font> as a Windows Service under Vista==
This section applies to situations in which Tomcat is not to be installed as a Windows service. This is rare in a Windows environment, and to date, it has only been used in Tomcat 5.5, so the instructions assume that version.

If Tomcat is not to be installed as a Windows service, it must be installed by expanding the Tomcat zip file. This in turn requires that the Java Developer's Kit (JDK) be installed rather than just the JRE.

===Install the Java Developer's Kit===
Download the latest standard edition JDK for Windows from http://java.sun.com/javase/downloads/index.jsp. It will have a name like <b>jdk-6u1-windows-i586-p.exe</b>.

If you obtained a MIRC Installation CD at the 2008 RSNA annual meeting, the JDK is in the <b>MIRC_Installation/Java/Windows_Vista</b> folder.

Run the file. The installer will provide a page for selecting which components to install. It is safe to accept the defaults, but you can save space by deselecting the documentation and the source code. The other components in the selection list are required.

===Install the JAI ImageIO Tools===
Download the latest release of the Java Advanced Imaging ImageIO Tools for the JDK from http://java.sun.com/products/java-media/jai/downloads/download-iio-1_0_01.html. Select the <b>JDK Install</b> version. It will have a name like <b>jai_imageio-1_1-lib-windows-i586-jdk.exe</b>. Note that the ImageIO Tools are separate from the JAI, so be careful to select the correct product for downloading. The JAI itself is <b>not</b> required.

If you obtained a MIRC Installation CD at the 2008 RSNA annual meeting, the ImageIO Tools file is in the <b>MIRC_Installation/JAI/Windows_Vista</b> folder.

Run the file and accept all the defaults.

===Define a System Variable for Java===
After installing the JDK and the ImageIO Tools, you must define a system
variable which points to the JDK. This will allow Tomcat to find
Java when it starts. If you install the JDK in the standard
place, it will be in a directory with a path like: <b>C:\Program Files (x86)\Java\jdk1.6.0_01</b>, where the numbers after <b>jdk</b> depend on the release which you installed.

* Click the <b>Start</b> button.
* Right-click the <b>Computer</b> button in the Start menu.
* Select <b>Properties</b> in the pop-up menu. 
* In the Tasks pane, click <b>Advanced System Settings</b>.
* If the User Account Control dialog appears, click <b>Continue</b>.
* In the System Properties dialog, click the <b>Advanced</b> tab.
* Click the <b>Environment Variables</b> button. 
* In the lower part of the next window, click <b>New...</b>. 
* In the <b>Variable name</b> field, enter: <b>JAVA_HOME</b>
* In the <b>Variable value</b> field, enter the path to the JDK.
* Finally, click OK on all the dialogs.

===Install Tomcat===
Obtain the latest Tomcat 5.5 Core zip file from http://tomcat.apache.org/download-55.cgi. Be careful to obtain 5.5 rather than 5.0, which is also available on the same page. It will have a name like <b>apache-tomcat-5.5.23.zip</b>.

If you obtained a MIRC Installation CD at the 2008 RSNA annual meeting, the Tomcat 5.5 Core zip file is in the <b>MIRC_Installation/Tomcat/Vista_and_Linux</b> folder.

Expand the zip file. A convenient place to put it is in the root of the C drive.

===Install the Apache Portable Runtime===
This step is optional, but it is highly recommended. It will give Tomcat the speed of a native implementation using the Apache server code.

Obtain the Apache Portable Runtime from http://mirc.rsna.org/APR/tc-native-1.dll.

If you obtained a MIRC Installation CD at the 2008 RSNA annual meeting, the Apache Portable Runtime file is in the <b>MIRC_Installation/Tomcat/Windows_except_Vista/Portable_Runtime</b> folder. (That is <u>not</u> a typo: Windows_<b>except</b>_Vista.)

Put the file in Tomcat's <b>bin</b> directory.

===Configure the Memory Settings===
This step is optional. It is recommended if you plan to support large (CR) images.

After installation, there will be a folder with a name like <b>apache-tomcat-5.5.23</b> containing numerous subfolders, including one called <b>bin</b>.

Open the <b>bin</b> directory and then open the <b>catalina.bat</b> file with a text editor like NotePad or TextPad. The top part of the file is a set of comments. About 55 lines from the top, the comments section ends. The last few lines of the comments section and the first few lines that follow it look like this:

<pre>
#
# $Id: catalina.sh 498126 2007-01-20 15:38:39Z markt $
# -----------------------------------------------------------------------------

rem Guess CATALINA_HOME is not defined
set CURRENT_DIR=%cd%
</pre>

Paste the line below into the file just after the comments section and then save the file.
		
:<b>set CATALINA_OPTS=-Xms256m -Xmx512m</b>

The result should look like this:

<pre>
#
# $Id: catalina.sh 498126 2007-01-20 15:38:39Z markt $
# -----------------------------------------------------------------------------

set CATALINA_OPTS=-Xms256m -Xmx512m

rem Guess CATALINA_HOME is not defined
set CURRENT_DIR=%cd%
</pre>

===Define a System Variable for Tomcat===
Use the procedure described above for the <b>JAVA_HOME</b> system variable to define another system variable named <b>CATALINA_HOME</b>. If the top-level Tomcat folder is located at C:\apache-tomcat-5.5.23, then set the value of the variable to <b>C:\apache-tomcat-5.5.23</b>.

===Starting and Stopping Tomcat===
To start Tomcat, open a command window, and enter: <b>%CATALINA_HOME%\bin\startup.bat</b>. Tomcat will start and open its own command window. You can close the original command window, but do not close Tomcat's window while Tomcat is running.

To stop Tomcat, open a command window, and enter: <b>%CATALINA_HOME%\bin\shutdown.bat</b>.

You may find it convenient to create a shortcut which starts a command window in the %CATALINA_HOME%\bin directory. This would allow you to start and stop Tomcat just by typing <b>startup</b> and <b>shutdown</b>.

==Installing MIRC==
To install and configure MIRC, follow the instructions available on the [[Downloads]] page of the wiki. The link is also shown in the navigation pane at the top left of this page. The instructions provide a link to the latest version of the MIRC installer.

If you obtained a MIRC Installation CD at the 2008 RSNA annual meeting, the MIRC installer is in the <b>MIRC_Installation/MIRC</b> folder. (There may be a newer version in the official release directory indicated in the instructions.)