erlsrv {set | add} <service-name> [<service options>]¶

The set and add commands modifies or adds an Erlang service, respectively. The simplest form of an add command is without any options in which case all default values (described above) apply. The service name is mandatory.

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, erlsrv set myservice -prio -arg sets the default priority and removes all arguments.

Service options:

-st[opaction] [<erlang shell command>]

-on[fail] [{reboot | restart | restart_always}]

-m[achine] [<erl-command>]

-e[nv] [<variable>[=<value>]] ...

-w[orkdir] [<directory>]

-p[riority] [{low|high|realtime}]

{-sn[ame] | -n[ame]} [<node-name>]

-d[ebugtype] [{new|reuse|console}]

-ar[gs] [<limited erl arguments>]

-i[nternalservicename] [<internal name>]

-c[omment] [<short description>]

erlsrv {start | start_disabled | stop | disable | enable} <service-name>¶

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 start and stop commands communicates with the service manager for starting and stopping a service. The commands wait until the service is started or stopped. When disabling a service, it is not stopped, the disabled state does not take effect until the service is stopped. Enabling a service sets it in automatic mode, which is started at boot. This command cannot set the service to manual.

The start_disabled command operates on a service regardless of if it is enabled/disabled or started/stopped. It does this by first enabling it (regardless of if it is enabled or not), then starting it (if not already started), and then disabling it. The result is a disabled but started service, regardless of its earlier state. This is useful for starting services temporarily during a release upgrade. The difference between using start_disabled and the sequence enable, start, and disable is that all other erlsrv commands are locked out during the sequence of operations in start_disable, making the operation atomic from an erlsrv user's point of view.

erlsrv remove <service-name>¶

Removes the service completely with all its registered options. It is stopped before it is removed.

erlsrv list [<service-name>]¶

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.

erlsrv help¶

Displays a brief help text.

Environment¶

The environment of an Erlang machine started as a service contains two special variables:

ERLSRV_SERVICE_NAME

ERLSRV_EXECUTABLE

A command file for restarting a service looks as follows:

@echo off
%ERLSRV_EXECUTABLE% stop %ERLSRV_SERVICE_NAME%
%ERLSRV_EXECUTABLE% start %ERLSRV_SERVICE_NAME%
    

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

Port Programs¶

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 SetConsoleCtrlHandler to register a control handler that returns true in answer to the CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT events. Other applications only forward WM_ENDSESSION and WM_QUERYENDSESSION to the default window procedure.

A brief example in C of how to set the console control handler:

#include <windows.h>
/*
** 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);


    }
}
    

Notes¶

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.

Note that the program resides in the emulator's bin directory, not in the bin directory directly under the Erlang root. The reasons for this are the subtle problem of upgrading the emulator on a running system, where a new version of the runtime system should not need to overwrite existing (and probably used) executables.

To manipulate the Erlang services easily, put the <erlang_root>\erts-<version>\bin directory in the path instead of <erlang_root>\bin. The erlsrv program can be found from inside Erlang by using the os:find_executable/1 Erlang function.

For release handling to work, use start_erl as the Erlang machine. As stated above, the service name is significant.

See Also¶

start_erl(1), release_handler