Readme for ServiceInstaller v. 1.3 for Windows NT Copyright (C) 2000 by Bill Giel/KC Multimedia and Design Group All Rights Reserved. October 5, 2000 ============================================================== Contents of this Readme ----------------------- 1. Overview 2. Installing over a previous version of ServiceInstaller 3. Installation 4. Using ServiceInstaller (Graphical Interface) 5. Installing Java Applications 6. Command Line Service Installations and Removals 7. Important JDK 1.3 information 8. FAQ 1. Overview ----------- ServiceInstaller consists of two programs: a graphical service configuration program that features an easy-to-use interface for installing and removing NT services (servinst.exe) and a Win32 console application that permits optional command-line installation of NT services, and actually runs your applications as services (srunner.exe) 2. Installing over a previous version of ServiceInstaller --------------------------------------------------------- You'll have to stop any services that have been started using a previous version of ServiceInstaller (or ServiceMaster). Note the name of the original installation directory. Then uninstall the old version using Control Panel|Add-Remove Programs. Then re-install the new version into the same installation directory as the old version. Following this procedure will permit your existing services that were created using previous versions of ServiceInstaller (or ServiceMaster) to function properly. After ServiceInstaller is installed, you can restart the stopped services. 3. Installation --------------- Install the programs into a directory on your computer's hard disk. By default, ServiceInstaller installs itself into a folder named c:\smaster. Do not separate the programs. Leave srunner.exe in the same folder as servinst.exe. If you separate these programs to different locations, your servinst-installed services will not work. Also, do not move the programs to a different directory after installing services with ServiceInstaller. If you do, you must remove the services that were installed with ServiceInstaller, and reinstall them. 4. Using ServiceInstaller (Graphical Interface) ----------------------------------------------- Run the program servinst.exe. Fill in the fields in the dialog box that will be displayed. Press the 'Help' button to display a short help file that explains each field. To install a service, provide a service name, display name, start type, dependencies (if any, separated by semicolons) full path and name of your executable that you want to run as a service, and arguments (if any) to your executable, separated by spaces. Enter the arguments exactly as you would enter them if you were running the application from the command line. Note: Do not supply an executable path that contains embedded spaces. See limitations described below for a workaround. To remove a service, enter the service name and press the Remove button. ServiceInstaller will check to see if it originally installed the service, and ask you to confirm removal. If servinst was not used to install the service, it will display a bold warning cautioning against removal of essential services and require a second confirmation to remove the service. 5. Installing Java Applications ------------------------------- You can use ServiceInstaller to install pure Java applications as NT services. Select java.exe or jre.exe as the executable, and specify your application in the arguments field. Be sure to supply all appropriate arguments, including fully qualified classpath and other JVM settings, followed by your applications main class, and any application specific arguments. Simply provide an argument field that looks exactly like what would be typed if you were running your application from the command line. Note that if you are using JDK 1.1 you should include the Java core classes (\lib\classes.zip) in your -classpath argument. This is not necessary with Java 2. 6. Command Line Service Installations and Removal ------------------------------------------------- It is not necessary to use the servinst.exe graphical service installer utility. Srunner.exe can also install itself as a service from a command line (making this useful for batch or scripted installations.) *** Service Installation Usage: srunner where "filename" is the name of a text file containing the same data entered into the ServiceInstaller graphical user interface, and in the format prescribed below: Service Name (In the FIRST line of the text file...) Display Name Startup Type ("Automatic" or "Manual", no quotes) Dependencies (blank line if none) Executable File (full path) Arguments (blank line if none) Working Directory (blank line for default) Note that a service's default working directory is winnt\system32. The textfile containing the service parameters must contain the above data in eight lines of text, with the eigth (last) line containing the string "". Blank lines must be used as indicated above. Srunner will echo the parameters and a few other messages to the stdout output device. *** Service Removal Usage: srunner -r where "ServiceName" is the registry name of the Service (not the Display name.) srunner.exe can also display a usage summary: Srunner -? 7. Important JDK 1.3 information ------------------------------------ At the time of writing this, we have noted a problem that occurs if the JDK 1.3 java runtimes are used. Services with this embedded VM will start normally and run, but the VM will stop when the user logs off. (This behavior does not occur with JDK 1.2.2 or JDK 1.1.x VM's.) We are aware of two solutions. JVMI, Our inexpensive substitute for java.exe keeps running with JDK 1.3 through a logoff. See www.kcmultimedia.com/jvmi for details. We also offer our free Javaserv tutorial at www.kcmultimedia.com/javaserv which provides complete source code for an easily customized invoker that optionally self-installs as a service. 8. Frequently Asked Questions ----------------------------- Can my service display any windows on the desktop? Yes. After installing your service open the Control Panel's services applet, select the service and under Startup... options, check the option to "Interact with Desktop" My java app is not running, although NT says the service is started. In this situation, you should enable "Interact with Desktop" (see above) so that you might see error messages reported by Java. Such cases are nearly always due to a typo in the classpath or other arguments supplied when installing the service. The recommended procedure is to try running your app from the console before installing it as a service, and note the exact arguments used for a successful run. These should be duplicated when you install your app as a service. Remember that NT services run in the winnt/system32 directory by default. If your Java app expects to find support files or write log files, you should supply the name of the app's working directory when you install the service. If you are using JDK 1.1.x, you must specify the path to Java's classes.zip in the classpath argument, along with your own classpath directories. With Java 2, you only have to specify the path to your own classes, using the -cp switch to the Java VM. Also, see note 7 above, concerning JDK 1.3 RC2, if that is the version of Java being used. My java app should generate a log file, but I cannot find it. If you did not specify a working directory, look in winnt/system32 for your output file. If it is not there, then run the service with "Interact with Desktop" enabled, and watch for error messages in the resulting console. You can also check NT's event viewer for certain error messages that srunner will post if it cannot start the service.