Difference between revisions of "Running CTP as a Windows Service"

From MircWiki
Jump to navigation Jump to search
 
(40 intermediate revisions by the same user not shown)
Line 1: Line 1:
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.
+
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.  
  
 
==Background==
 
==Background==
The [http://mirc.rsna.org/CTP/CTP-installer.jar CTP installer] program is a self-extracting program that copies all the necessary files into a directory called <b><tt>CTP</tt></b> wherever the user requests it to be created. The installer creates a <b><tt>windows</tt></b> subdirectory containing these files:
+
The [http://mirc.rsna.org/download/CTP-installer.jar CTP installer] program is a self-extracting program that copies all the necessary files into a directory called <b><tt>CTP</tt></b> wherever the user requests it to be created. The installer creates a <b><tt>windows</tt></b> subdirectory containing these files:
  
 
*<b>CTP.exe</b> - the service which is run by the Windows service manager. It starts and stops the CTP.jar program.
 
*<b>CTP.exe</b> - the service which is run by the Windows service manager. It starts and stops the CTP.jar program.
Line 8: Line 8:
 
*<b>install.bat</b> - the Windows batch job which installs the CTP.exe service and provides a default set of parameters.
 
*<b>install.bat</b> - the Windows batch job which installs the CTP.exe service and provides a default set of parameters.
 
*<b>uninstall.bat</b> - the Windows batch job which uninstalls the CTP.exe service.
 
*<b>uninstall.bat</b> - 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.)
 
  
 
==Installing the CTP Service==
 
==Installing the CTP Service==
Line 21: Line 19:
 
</ol>
 
</ol>
 
<ol start="3">  
 
<ol start="3">  
<li> Navigate to the <b>CTP</b> directory
+
<li> Navigate to the <b>CTP\windows</b> directory
 
<li> Enter the command: <b><tt>install.bat</tt></b>
 
<li> Enter the command: <b><tt>install.bat</tt></b>
 
<li> Close the command window
 
<li> Close the command window
Line 36: Line 34:
 
</ol>
 
</ol>
 
<ol start="3">  
 
<ol start="3">  
<li>Navigate to the <b>CTP</b> directory.
+
<li>Navigate to the <b>CTP\windows</b> directory.
 
<li> Enter the command: <b><tt>uninstall.bat</tt></b>
 
<li> Enter the command: <b><tt>uninstall.bat</tt></b>
 
<li> Close the command window
 
<li> Close the command window
 
</ol>
 
</ol>
 +
==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 <b>msvcr71.dll</b>. If CTP fails to start and the CTP/logs directory doesn't indicate another problem, the simplest thing to do is place a <u>copy</u> of the file in the Java <b>jre\bin</b> directory. The file can usually be found in the <b>C:\Windows\System32</b> directory. Do <u>not</u> remove the file from where you found it.
  
 
==Changing the Service Parameters with the CTP Service Monitor==
 
==Changing the Service Parameters with the CTP Service Monitor==
The <b>CTPw.exe</b> program provides control over all the parameters that the service uses. To run the program, <b>right</b>-click the program and select <b>Run as administrator</b>. It displays this CTP Properties dialog:
+
The <b>CTPw.exe</b> program provides control over all the parameters that the service uses. To run the program, double-click the <b>CTPw.exe</b> file. If Windows displays the User Account Control challenge, click <b>Allow</b>. The program displays the CTP Properties dialog:
 
[[Image:CTP-properties-1.JPG|center]]
 
[[Image:CTP-properties-1.JPG|center]]
  
Line 51: Line 51:
  
 
===Changing the Java Parameters===
 
===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, it may be necessary to change these settings. To do so, click the <b>Java</b> tab to see this page:
+
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 <b>Java</b> tab to see this page:
 
[[Image:CTP-properties-2.JPG|center]]
 
[[Image:CTP-properties-2.JPG|center]]
 +
 +
===Changing Other Parameters===
 +
 +
If you upgrade your Java and the <b>Use default</b> box is checked on the <b>Java</b> 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 <b><tt>jvm.dll</tt></b> file.
 +
 +
Sophisticated administrators may consider changing the account under which the service runs. This can be done on the <b>Log On</b> tab.
 +
 +
Do <u>not</u> 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 <b><tt>CTP/libraries</tt></b> directory. See [[Extending CTP]], and note especially [[Extending CTP#Building an Extension JAR | Building an Extension JAR]].
  
 
==Technical Details==
 
==Technical Details==
This section is included only for the interested technophile. It contains secret, highly technical information which will make you extremely attractive to women. Proceed at your own risk.  
+
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 <b>CTP.exe</b> program is the Apache Commons Daemon</b> 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 <b>CTP.exe</b> program is the <b>Apache Commons Daemon</b> 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 <b>install.bat</b> file provides all the parameters required to make it launch CTP.jar. The CTP installer modifies a template <b>install.bat</b> file when it installs the file in the <b><tt>CTP\windows</tt></b> directory, replacing the <b><tt>${home}</tt></b> fields with the actual path to the <b><tt>CTP</tt></b> directory. This is the template file:
+
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 <b><tt>install.bat</tt></b> file provides all the parameters required to run the service and launch CTP.jar. The CTP installer modifies a template <b><tt>install.bat</tt></b> file when it installs the file in the <b><tt>CTP\windows</tt></b> directory, replacing the <b><tt>${home}</tt></b> fields with the absolute path to the <b><tt>CTP</tt></b> directory. This is the template file:
  
 
<pre>
 
<pre>
 
CTP.exe ^
 
CTP.exe ^
 
  //IS//CTP ^
 
  //IS//CTP ^
  --Install=D:\JavaPrograms\CTP\windows\CTP.exe ^
+
  --Install="${home}"\windows\CTP.exe ^
 
  --Description="RSNA CTP Service" ^
 
  --Description="RSNA CTP Service" ^
 +
--Startup="auto" ^
 
  --Jvm=auto ^
 
  --Jvm=auto ^
--Classpath=D:\JavaPrograms\CTP\CTP.jar;D:\JavaPrograms\CTP\libraries\util.jar ^
 
 
  --StartMode=jvm ^
 
  --StartMode=jvm ^
 
  --JvmMs=128 ^
 
  --JvmMs=128 ^
 
  --JvmMx=512 ^
 
  --JvmMx=512 ^
  --StartPath=D:\JavaPrograms\CTP ^
+
  --Classpath="libraries\CTP.jar" ^
 +
--StartPath="${home}" ^
 
  --StartClass=org.rsna.ctp.ClinicalTrialProcessor ^
 
  --StartClass=org.rsna.ctp.ClinicalTrialProcessor ^
 
  --StartMethod=startService ^
 
  --StartMethod=startService ^
 
  --StartParams=start ^
 
  --StartParams=start ^
 
  --StopMode=jvm ^
 
  --StopMode=jvm ^
  --StopPath=D:\JavaPrograms\CTP ^
+
  --StopPath="${home}" ^
 
  --StopClass=org.rsna.ctp.ClinicalTrialProcessor ^
 
  --StopClass=org.rsna.ctp.ClinicalTrialProcessor ^
 
  --StopMethod=stopService ^
 
  --StopMethod=stopService ^
 
  --StopParams=stop ^
 
  --StopParams=stop ^
  --LogPath=D:\JavaPrograms\CTP\logs ^
+
  --LogPath="${home}"\logs ^
 
  --StdOutput=auto ^
 
  --StdOutput=auto ^
 
  --StdError=auto
 
  --StdError=auto
 
</pre>
 
</pre>
The full set of parameters which the service supports is listed on the Apache Commons website at http://commons.apache.org/daemon/procrun.html.
+
The full set of parameters which the service supports is described on the [http://commons.apache.org/daemon/procrun.html Apache Commons] website.
  
The <b>uninstall.bat</b> file is very simple:
+
The <b><tt>uninstall.bat</tt></b> file is very simple:
 
<pre>
 
<pre>
 
CTP.exe //DS//CTP  
 
CTP.exe //DS//CTP  
 
</pre>
 
</pre>
 +
 +
The <b>CTPw.exe</b> 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.

Latest revision as of 15:54, 30 November 2019

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
  1. Navigate to the CTP\windows directory
  2. Enter the command: install.bat
  3. 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
  1. Navigate to the CTP\windows directory.
  2. Enter the command: uninstall.bat
  3. 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.