Running CTP as a Windows Service

This article describes how to install CTP as a Windows service. It is intended for administrators who want CTP to start automatically when its host computer starts and shut down cleanly when its host computer shuts down. This is the most convenient way to run CTP on a Windows system for applications in which CTP acts a resource for a clinical trial or as a front-end to another system. This article is written for Windows Vista and Windows 7, but it also works for Windows XP if you ignore the issues associated with User Account Control.

1 Background

The CTP installer program is a self-extracting program that copies all the necessary files into a directory called CTP wherever the user requests it to be created. The installer creates a windows subdirectory containing these files:

• CTP.exe - the service which is run by the Windows service manager. It starts and stops the CTP.jar program.
• CTPw.exe - the service monitor which allows the administrator to adjust the parameters which determine how CTP.jar runs.
• install.bat - the Windows batch job which installs the CTP.exe service and provides a default set of parameters.
• uninstall.bat - the Windows batch job which uninstalls the CTP.exe service.

To run CTP as a Windows service, the 32-bit Java must be installed. (This is necessary anyway, even for non-service CTP installations, since most applications of CTP require the JAI ImageIO Tools, which are only available in a 32-bit version. In any application, it is not possible to mix 32-bit and 64-bit libraries on a Windows system.)

2 Installing the CTP Service

To install the service:

1. Log into Windows in an account with administrator privileges
2. Launch a command window with administrator privileges

   • Click Start
   • Type cmd
   • Type Ctrl-Shift-Enter

3. Navigate to the CTP directory
4. Enter the command: install.bat
5. Close the command window

3 Uninstalling the CTP Service

To uninstall the service:

1. Log into Windows in an account with administrator privileges
2. Launch a command window with administrator privileges

   • Click Start
   • Type cmd
   • Type Ctrl-Shift-Enter

3. Navigate to the CTP directory.
4. Enter the command: uninstall.bat
5. Close the command window

4 Changing the Service Parameters with the CTP Service Monitor

The CTPw.exe program provides control over all the parameters that the service uses. To run the program, right-click the program and select Run as administrator. It displays this CTP Properties dialog:

Error creating thumbnail: Unable to save thumbnail to destination

The properties dialog can be used to start or stop the service manually, but it is generally better to use the Windows service manager.

4.1 Changing the Startup Type

The CTP service is initially configured to require that the service be started manually. This can be changed to Automatic on the General tab if it is necessary that the service start automatically when the host computer starts.

4.2 Changing the Java Parameters

The CTP service is initially configured to allocate 128MB to the Java memory pool and to allow the memory pool to expand to 512MB if necessary as it runs. For most applications, this is sufficient. For systems which implement many pipelines handling large images or which employ pipeline stages which build large databases, it may be desirable to change these settings. To do so, click the Java tab to see this page:

Error creating thumbnail: Unable to save thumbnail to destination

4.3 Changing Other Parameters

If you upgrade your Java and the Use default box is checked on the Java tab, the service will switch to the new Java the next time it starts. If you have multiple Java versions and you want to run a different one from the default, uncheck the box and specify the path to the desired jvm.dll file.

Sophisticated administrators may consider changing the account under which the service runs. This can be done on the Log On tab.

Do not change the Java Classpath parameter, even if you are a developer and you think you must. The Java Classpath parameter is only used to get CTP.jar running. After that, CTP instantiates its own classloader, which ignores the classpath. See Extending CTP, and note especially Building an Extension JAR. If you want all the details about CTP classloading, see The CTP JarClassLoader.

5 Technical Details

This section is included for the interested technophile. The information contained in this section is not required for installation or operation of the program.

The CTP.exe program is the Apache Commons Daemon which is used to run Tomcat. It is used here with no modification except to change its name. The name defines the name by which the Windows service manager knows the service, and it cannot be changed without uninstalling the service and reinstalling it under a new name.

The daemon calls a static start method in the main class of the Java program it runs. The daemon requires that the start method not return until the Java program ends. The daemon stops the Java program by calling a static stop method. The start and stop classes and methods are specified when the service is installed, and they are stored in the Windows registry.

The install.bat file provides all the parameters required to run the service and launch CTP.jar. The CTP installer modifies a template install.bat file when it installs the file in the CTP\windows directory, replacing the ${home} fields with the actual path to the CTP directory. This is the template file:

CTP.exe ^
 //IS//CTP ^
 --Install=${home}\windows\CTP.exe ^
 --Description="RSNA CTP Service" ^
 --Jvm=auto ^
 --Classpath=${home}\CTP.jar;${home}\libraries\util.jar ^
 --StartMode=jvm ^
 --JvmMs=128 ^
 --JvmMx=512 ^
 --StartPath=${home} ^
 --StartClass=org.rsna.ctp.ClinicalTrialProcessor ^
 --StartMethod=startService ^
 --StartParams=start ^
 --StopMode=jvm ^
 --StopPath=${home} ^
 --StopClass=org.rsna.ctp.ClinicalTrialProcessor ^
 --StopMethod=stopService ^
 --StopParams=stop ^
 --LogPath=${home}\logs ^
 --StdOutput=auto ^
 --StdError=auto

The full set of parameters which the service supports is described on the Apache Commons website.

The uninstall.bat file is very simple:

CTP.exe //DS//CTP 

The CTPw.exe program is the Apache service monitor which is part of the Commons Daemon project. It is used here with no modification except to change the name. The name of the program must correspond to the name of the service program. For example, CTPw.exe corresponds to CTP.exe, and tomcat6w.exe corresponds to tomcat6.exe.

Two changes are planned for the CTP service implementation:

• CTPw.exe will be modified so that it elevates its privileges automatically so the user can simply double-click it to run it. This will still present the UAC dialog, but it will at least simplify the launch of the program.
• An application will be provided to do the service installation without having to launch a command window and navigate to the CTP directory.

Neither of these changes will invalidate the instructions and description provided in this article.