PerlSvc - Overview

What is PerlSvc?

The PerlSvc utility converts a Perl program to a native Windows service with an .exe extension. There are two types of services that can be generated:

• Dependent: the target computer must have ActivePerl installed.

• Freestanding: the target computer does not need to have ActivePerl installed.

What is required for PerlSvc?

The following global functions are available to your script:

• PerlSvc::ContinueRun( [DELAY] )

  Returns false when the service has received a stop command. Optionally, ContinueRun() waits for DELAY seconds, except for the very first time it is called. When the service receives a STOP, PAUSE or SHUTDOWN command, ContinueRun() aborts the delay and immediately returns a false value.

• PerlSvc::Sleep(DELAY)

  Sleep() suspends execution for DELAY seconds. When the service receives a STOP, PAUSE or SHUTDOWN command, Sleep() aborts the delay and returns immediately.

• PerlSvc::RunningAsService()

  Returns true when the program is running as a service.

Your script must define:

• $PerlSvc::Name

  The short name by which your service is known.

• $PerlSvc::DisplayName

  The display name. This is the name that the Windows Control Panel displays.

• PerlSvc::Startup()

  The function called when the service is started.

Your script can optionally define:

• PerlSvc::Install()

  Called when the resulting executable is started with the --install option, after the service has been installed successfully.

• PerlSvc::Remove()

  Called when the resulting executable is started with the --remove option, after the service has been uninstalled successfully.

• PerlSvc::Help()

  Called when the resulting executable is started with the --help option.

• PerlSvc::Interactive()

  The Interactive() callback is invoked if the program is not running as a service and none of the --help, --install or --remove command-line options have been specified.

• PerlSvc::Pause()

  Pause() is called by the ContinueRun() function when the service receives a PAUSE request. After Pause() returns, ContinueRun() suspends execution until a CONTINUE, STOP or SHUTDOWN request is received.

• PerlSvc::Continue()

  Continue() is invoked from ContinueRun() after a CONTINUE command has been received. ContinueRun() immediately returns with a true value after Continue() has finished execution, aborting any potential pending DELAY activity. The Continue() callback is not invoked if the PAUSE state is terminated by a STOP or SHUTDOWN command.

To suppress display of the default messages from PerlSvc::Install(), PerlSvc::Remove() and PerlSvc::Help(), set the global variable $PerlSvc::Verbose to 0:

    $PerlSvc::Verbose = 0;

PerlSvc provides a flexible way to configure a service. If $PerlSvc::Name is not defined, then PerlSvc::Install and PerlSvc::Remove are executed before the service is installed or removed. They must initialize the %PerlSvc::Config hash with at least the ServiceName and DisplayName fields before returning. Additional supported fields in the %PerlSvc::Config hash are:

• Parameters

  Command-line parameters that are passed to the executable (in @ARGV) when started as a service.

• StartType

  Can be one of 'auto', 'demand' or 'disabled'. The default is 'demand'. When the service is started with myservice --install auto, this field is preset to 'auto'.

  In the Windows services management console these settings are called 'Automatic', 'Manual' and 'Disabled'.

• StartNow

  By default, PerlSvc immediately starts a service after it has been installed if it uses the StartType 'auto'. If StartNow is set to a true value, the service is always started (unless the StartType is 'disabled'). If StartNow is a defined false value, then the service won't be started immediately, independent of the StartType.

• UserName

• Password

  The username and password associated with the service. If not specified, the service runs using the LocalSystem account. The UserName should be in the form 'DomainName\UserName'. If the account belongs to the built-in domain, specify '.\UserName'.

• Interactive

  This field should be set to any TRUE value if the service needs to interact with the desktop. This is only valid when running under the LocalSystem account (UserName and Password must not be set).

• Description

  An optional long description of the service that is displayed in the Windows Management Console.

• Dependencies

  A list of names of services that must be started before this service. This parameter can be either a string or a reference to an array of strings.

Freestanding Executables

You can deploy a freestanding service on a system with or without ActivePerl installed.

The following example creates a freestanding executable file named myservice.exe from Perl script myservice.pl with verbose feedback:

    perlsvc --verbose myservice.pl

To install the program as a service, you have to invoke it with the --install option:

    myservice --install auto

The optional auto argument tells the service control manager to automatically start the service when the operating system is loaded. To start the service manually (or to start it right away without restarting the computer) use the net start command:

    net start TestSvc

This assumes that you used TestSvc as the $Name for your service. You have to explicitly stop the service before you can uninstall it:

    net stop TestSvc
    myservice --remove

What PerlSvc Includes in Freestanding Executables

PerlSvc can package a Perl program and the required Perl modules into the binary executable. When the service is run, it searches for modules within itself before searching the filesystem. Building freestanding services with PerlSvc ensures that your executable is always executed by the desired version of Perl, even if the target system is running a different version.

PerlSvc includes modules that are mentioned in require or use statements.

For example, if you have file A.pm that requires B.pm, which requires C.pm, PerlSvc brings in all of these packages. However, PerlSvc does not include modules that are mentioned in a variable. For example, in a script with the following line:

    require $module;

PerlSvc does not include the module identified by $module. To explicitly include this module, rebuild the PerlSvc using the --add list command-line switch, where list is a semicolon-delimited list of the modules you want to explicitly include.

PerlSvc detects which DLLs have been loaded by the *.pm files. However, if a DLL loaded by a .pm file depends upon a second DLL, the second DLL is not bound into the executable. Otherwise, PerlSvc would include numerous system DLLs.

Dynamic Service Names

It is possible to dynamically choose a service name (e.g. based on a command-line parameter during --install time). To be effective, $PerlSvc::Name must be set in the body of the file, before PerlSvc calls the Install() callback.

When the service is started, PerlSvc automatically sets $PerlSvc::Name to the correct service name immediately before calling Startup(). The service name will not be known when the file scope statements are being executed.

The user must supply the service name at --remove time in order to uninstall the service. Again, $PerlSvc::Name must be set at file scope, before the Remove() callback is entered.