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.

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.

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\windows 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\windows directory.
4. Enter the command: uninstall.bat
5. Close the command window

4 C Runtime Library

When CTP runs as a Windows service, it requires the Microsoft C Runtime Library to be present. This is a file called msvcr71.dll. If CTP fails to start and the CTP/logs directory doesn't indicate another problem, the simplest thing to do is place a copy of the file in the Java jre\bin directory. The file can usually be found in the C:\Windows\System32 directory. Do not remove the file from where you found it.

5 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, double-click the CTPw.exe file. If Windows displays the User Account Control challenge, click Allow. The program displays the 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.

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

5.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 that implement many pipelines handling large images or that employ pipeline stages that 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

5.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 overwrites the classpath with the jars it finds in the CTP/libraries directory. See Extending CTP, and note especially Building an Extension JAR.

6 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 absolute path to the CTP directory. This is the template file:

CTP.exe ^
 //IS//CTP ^
 --Install="${home}"\windows\CTP.exe ^
 --Description="RSNA CTP Service" ^
 --Startup="auto" ^
 --Jvm=auto ^
 --StartMode=jvm ^
 --JvmMs=128 ^
 --JvmMx=512 ^
 --Classpath="libraries\CTP.jar" ^
 --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 and to force it to run with elevated privileges, thus allowing it to be run with a simple double-click. 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.