This utility is specific to Windows NT/2000/XP (and later versions of Windows). It allows Erlang emulators to run as services on the Windows system, allowing embedded systems to start without any user needing to log on. The emulator started in this way can be manipulated through the Windows services applet in a manner similar to other services.
Notice that
To manipulate services, the logged on user is to have administrator privileges on the machine. The Erlang machine itself is (default) run as the local administrator. This can be changed with the Services applet in Windows.
The processes created by the service can, as opposed to normal services, be "killed" with the task manager. Killing an emulator that is started by a service triggers the "OnFail" action specified for that service, which can be a reboot.
The following parameters can be specified for each Erlang service:
Tells
Can be one of the following:
The Windows system is rebooted whenever the emulator stops (a more simple form of watchdog). This can be useful for less critical systems, otherwise use the heart functionality to accomplish this.
Makes the Erlang emulator be restarted (with whatever parameters are registered for the service at the occasion) when it stops. If the emulator stops again within 10 seconds, it is not restarted to avoid an infinite loop, which could hang the Windows system.
Similar to
Reports the service as stopped to the service manager whenever it fails; it must be manually restarted.
On a system where release handling is used,
this is always to be set to
The location of the Erlang emulator.
The default is the
If the system uses release handling, this is to be set to a
program similar to
Specifies an extra environment for the emulator. The environment variables specified here are added to the system-wide environment block that is normally present when a service starts up. Variables present in both the system-wide environment and in the service environment specification will be set to the value specified in the service.
The working directory for the Erlang emulator.
Must be on a local drive (no network drives are mounted when a
service starts). Default working directory for services is
The process priority of the emulator. Can be one of the following:
Not recommended, as the machine will possibly be inaccessible to interactive users.
Can be used if two Erlang nodes are to reside on one dedicated system and one is to have precedence over the other.
Can be used if interactive performance is not to be affected by the emulator process.
Specifies the short or long node name of the Erlang emulator. The Erlang services are always distributed. Default is to use the service name as (short) nodename.
Specifies that output from the Erlang shell is to be
sent to a "debug log". The log file is named
<servicename>
Can be one of the following:
Uses a separate log file for every invocation of the service
(<servicename>
Reuses the same log file
(<servicename>
Opens an interactive Windows console window for the Erlang
shell of the service. Automatically disables the
The output of the Erlang shell is discarded.
The
The
In short, the
Passes extra arguments to the emulator startup program
Specifies the Windows-internal service name (not the display name,
which is the one
This internal name cannot be changed, it is fixed even if the
service is renamed.
The internal service name can be seen in the Windows service
manager if viewing
A textual comment describing the service. Not mandatory, but shows up as the service description in the Windows service manager.
The
Every option can be specified without parameters, the
default value is then applied. Values to the options are
supplied only when the default is not to be used.
For example,
Service options:
Defines the
The action to take when the Erlang emulator stops unexpectedly. Default is to ignore.
The complete path to the Erlang emulator. Never use the
Edits the environment block for the service. Every
environment variable specified is added to the system
environment block. If a variable specified here has the same
name as a system-wide environment variable, the specified
value overrides the system-wide. Environment variables are
added to this list by specifying
<variable>=<value> and deleted from the list by
specifying <variable> alone. The environment block is
automatically sorted. Any number of
The initial working directory of the Erlang emulator. Defaults to the system directory.
The priority of the Erlang emulator. Default to the Windows default priority.
The node name of the Erlang machine. Distribution is mandatory.
Defaults to
Specifies where shell output is to be sent. Default is that shell output is discarded. To be used only for debugging.
Extra arguments to the Erlang emulator. Avoid
Only allowed for
Specifies a textual comment describing the service. This comment shows up as the service description in the Windows service manager.
These commands are only added for convenience, the normal way to manipulate the state of a service is through the control panels services applet.
The
The
Removes the service completely with all its registered options. It is stopped before it is removed.
If no service name is specified, a brief listing of all Erlang services is presented. If a service name is supplied, all options for that service are presented.
Displays a brief help text.
A command file for restarting a service looks as follows:
This command file is then set as heart command.
The environment variables can also be used to detect that we are running as a service and make port programs react correctly to the control events generated on logout (see the next section).
When a program runs in
the service context, it must handle the control events that are
sent to every program in the system when the interactive user
logs off. This is done in different ways for programs running in
the console subsystem and programs running as window
applications. An application running in the console subsystem
(normal for port programs) uses the win32 function
A brief example in C of how to set the console control handler:
/*
** A Console control handler that ignores the log off events,
** and lets the default handler take care of other events.
*/
BOOL WINAPI service_aware_handler(DWORD ctrl){
if(ctrl == CTRL_LOGOFF_EVENT)
return TRUE;
if(ctrl == CTRL_SHUTDOWN_EVENT)
return TRUE;
return FALSE;
}
void initialize_handler(void){
char buffer[2];
/*
* We assume we are running as a service if this
* environment variable is defined.
*/
if(GetEnvironmentVariable("ERLSRV_SERVICE_NAME",buffer,
(DWORD) 2)){
/*
** Actually set the control handler
*/
SetConsoleCtrlHandler(&service_aware_handler, TRUE);
}
} ]]>
Although the options are described in a Unix-like format, the case of the options or commands is not relevant, and both character "/" and "-" can be used for options.
Notice that the program resides in the emulator's
To manipulate the Erlang services easily, put
the
For release handling to work, use