Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
Showing results for 
Search instead for 
Did you mean: 

Web Dispatcher installations typically come in two variants: with and without SAP Start Service. The availability of command line control tools is slightly different between these two installation types. In this article, I want to explore some of the available tools and introduce a third-party (non-SAP) tool.

Standard tools

These are the tools that stand-alone and SAP Start Service installations have in common:

Controlling the sapwebdisp process with signals

The following signals can be sent to the sapwebdisp process:

USR1         Lowers the current trace level by one

USR2         Raises the current trace level by one

INT          Shutdown (If the sapwebdisp process is controlled by the SAP Start Service, a new process will likely be started immediately.)

To send a signal on Unix systems, you can use the regular kill command. On Windows, you can use the program sapntkill.exe which is part of each Web Dispatcher installation, e.g.:

sapntkill.exe -USR2 <pid>

Obviously, this method is only available locally on the machine on which the process is running.

Using the monitoring tool wdispmon

The wdispmon executable is part of any Web Dispatcher installation. It attaches to the sapwebdisp process through shared memory and can therefore be used only locally. There are two ways to employ wdispmon: as a command line tool and in an interactive menu-driven mode. Since I am focusing on command line controls for Web Dispatcher, I will not go into details about the interactive mode. Essentially, the interactive mode has the same functionality as the Web Admin Interface. This includes but is not limited to: increasing/decreasing the trace level and resetting the trace file, viewing overall  and thread status, as well as some statistics, displaying and changing profile parameters, displaying and resetting session tables.

The command line mode is much more limited and offers the following functions:

Usage:    wdispmon<options> pf=<profile>

with the following options:

  -version                Display version info and exit

  -info                   Return status of ICM/WebDisp through shared memory

  -ping                   Return status of ICM/WebDisp with request/response

  -checkhealth            Attach to ICM/WebDisp and return in case of error

  -a                      Maintain authentication file

  -function <function>    call monitoring function (like sapcontrol)







The -function option offers fewer commands than sapcontrol (see SAP Start Service below.) The -a option is actually not a real command line option because it will launch another interactive mode to maintain users and groups in the authentication file (usually: icmauth.txt.)

One option that is unique to wdipmon is -checkhealth: when started with this option, wdispmon will attach to the sapwebdisp process and will block and wait until the sapwebdisp process terminates (for whatever reason.) This might be useful in scripting environments to detect Web Dispatcher down situations.

SAP Start Service

The SAP Start Service framework contains a tool called sapcontrol, which adds a few more possibilities for command line control. sapcontrol -h will print the list of all known commands, but only a limited number actually makes sense for Web Dispatcher. Some of them are related to the start service itself.


    sapcontrol [-prot <protocol>]

               [-trace <filename>]


               [-user <user> <password>]


               [-repeat <N> <D>]

               [-format <format>]

               [-host <hostname>]

               -nr <instance number>

               -function <webmethod> [parameter list]


    Control and monitor SAP instances via WebService interface of SAP Start Service.


    -prot <protocol>

        Specify the protocol for the communication with the SAP instance.

        Available protocols are:

          NI_HTTP     HTTP  using SAP NI sockets (default, prefer Unix domain sockets)

          NI_HTTPS    HTTPS using SAP NI sockets (prefer Unix domain sockets)

          GSOAP_HTTP  HTTP  using gsoap build in sockets

          WINHTTP     HTTP  using Windows winhttp

          WINHTTPS    HTTPS using Windows winhttp

          PIPE        Windows named pipes (on Unix same as NI_HTTP)

    -trace <filename>

        Trace SOAP request/response


        Write local trace to stderr

    -user <user> <password>

        OS user and password for Webservice authentication


        Query interactively for user and password

    -repeat <N> <D>

        Repeat webmethod call <N> times (-1=forever) with <D> sec delay

    -format <format>

        Specify the format for the output of the webmethod.

        Available formats are:

          list    List output format (default)

          script  Script output format

    -host <hostname>

        Host to connect to (default: localhost)

Here is a list of "webmethods" that are useful for the control of Web Dispatcher:

command description

StartService <SID>
Launches the start service. The Web Dispatcher instance must be started separately.

Stops the start service, but not the Web Dispatcher instance.


A Web Dispatcher system usually consists of only one instance, so this command is equivalent to InstanceStart.

Usually equivalent to InstanceStop.


GetSystemInstanceList [<timeout sec>]
Prints a list of instances known to this system.

InstanceStart <hostname> <instance number>
Starts the instance with the given hostname and instance number.

InstanceStop <hostname> <instance number> [<softtimeout sec>]

Stops the instance with the given hostname and instance number.

RestartInstance [<softtimeout sec>]

Prints info about the sapwebdisp process, e.g. running status and pid.

SendSignal <pid> <signal>
Sends an OS signal to the sapwebdisp process. The pid can be determined with GetProcessList. See previous section for a list of valid signals.

Determines release and patch level for Web Dispatcher and Start Service.

Prints a list of the environment variables used by the Web Dispatcher system.

Prints the start profile that is used by the start service.

ParameterValue [<parameter>]
Prints a list of all profile parameters or one specific parameter.

Prints a list of access points (ports), including those of the start service.

Prints request queue statistics (peak, max).

Prints the status of all sapwebdisp threads, including the main thread, watchdog thread, and worker threads.

Prints a list of current front-end connections. (This does not include the connections to the back-end application servers.)

Prints a list of cached entries (in case the Web Dispatcher has an active cache handler.)

Prints a list of back-end application servers.

Prints a list of developer traces, including their file size and last modified time stamp.

ReadDeveloperTrace <filename> <filesize>
Downloads and prints the specified developer trace.

Prints the content of the SYSLOG.

Prints the unformatted content of the SYSLOG.

sapcontrol usually connects to the SAP Start Service over TCP/IP. It is therefore possible to control Web Dispatcher remotely by using the -host parameter. The sapcontrol executable does not have any dependencies and can be easily copied to other machines.

Third-party tools

The available standard tools are still missing a few features that could sometimes be useful, such as activating/deactivating specific application servers or ports, or putting the Web Dispatcher into maintenance mode. That is why I decided to write a simple Python application that provides some of these missing features.


The idea is to connect to the Web Admin Interface that is usually available for each Web Dispatcher. This interface is accessed through a specific URL prefix, such as /sap/wdisp/admin or /sap/admin (see profile parameter icm/HTTP/admin_0). Using this method to "web scrape" the Admin Interface has advantages and disadvantages:

+ remote control over the network

+ one tool can attach to multiple Web Dispatcher installations

+ all commands available through the Admin Interface could be used

- the stability of the application depends on the stability of the Admin Interface; each time the interface changes, the application might require adaption or fail to work

- there is no official support by SAP

wdcontrol can be downloaded here:

usage: [-h]

                    [--command {info,...}]

                    [--node NODE] [--stack {ABAP,J2EE,BOTH}] [--sid SID]

                    [--port PORT] [--admin ADMIN] [--proxy PROXY]

                    [--log {ERROR,WARN,INFO,DEBUG,OFF}] [--version]

                    [conf [conf ...]]

positional arguments:

  conf                  Configuration file(s) (default: wdcontrol.wdc)

optional arguments:

  -h, --help            show this help message and exit

  --command {info,...}  Command (default: info)                       

  --node NODE           Server node name (for 'isNodeActive' etc.)

  --stack {ABAP,J2EE,BOTH}  Stack type (default: BOTH)                       

  --sid SID             System ID (default: None)

  --port PORT           Port number (for 'isPortActive' etc.)

  --admin ADMIN         Web Admin Interface URL (format: http|https://user:pass@host[:port][/prefix])

  --proxy PROXY         HTTP proxy used to connect to Web Admin Interface (format: host:port; default: None)

  --log {ERROR,WARN,INFO,DEBUG,OFF}   log level (default: INFO)                       

  --version             Print version information and exit

wdcontrol is designed to be called with either command line arguments, configuration files, or a combination of both. The built-in help ( -h) provides detailed information about all command line arguments and configuration parameters.

A typical scenario would be the following configuration:

  • All parameters for the connection to the Admin Interface go into the default configuration file wdcontrol.wdc:

  "": "",
  "admin.port": 8000,
  "admin.password": "secret"

  • All parameters to identify a specific instance go into one configuration file for each instance, e.g. DEV_J2EE3565100.wdc:

  "": "J2EE3565100",
  "node.stack": "J2EE",
  "": "DEV"

  • Now it is easily possible to control instance related functions by using the configuration file and an appropriate command.
    N.B.: The default configuration file wdcontrol.wdc does not have to be specified, as it is loaded automatically. Examples: DEV_J2EE3565100.wdc --command isNodeActive

    All other commands that are not related to a specific instance can skip the configuration file. Examples: --command refresh --commmand isPortActive --port 8000

List of currently supported commands:

command description

Prints the status info for Web Dispatcher.
enterMaintenance Puts the Web Dispatcher into maintenance mode.
leaveMaintenance Puts the Web Dispatcher into normal mode.
refresh Triggers a refresh of the configuration (server info, ...)
shutdown Sends a shutdown command to the Web Dispatcher. This will terminate the sapwebdisp process. If Web Dispatcher is controlled by SAP Start Service, it will likely be restarted immediately.
downloadDefaultProfile Downloads and prints the default profile.
downloadInstanceProfile Downloads and prints the instance profile.
traceLevel0, traceLevel1, traceLevel2, traceLevel3 Sets the trace level to 0, 1, 2, or 3, then prints the current level.
downloadTrace Downloads and prints the trace file dev_webdisp.
listPorts Prints a JSON formatted list of all known ports.
isPortActive Prints 'True'/'False' if the port is active/inactive.
activatePort Activates the port, then prints its status (see 'isPortActive'.)
deactivatePort Deactivates the port, then prints its status (see 'isPortActive'.)
listNodes Prints a JSON formatted list of all known application servers.
isNodeActive Prints 'True'/'False' if the application server is active/inactive.
activateNode Activates the application server, then prints its status (see 'isNodeActive'.)
deactivateNode Deactivates the application server, then prints its status (see 'isNodeActive'.)

The printed output of most of the commands is designed to be used in scripting environments. Complex data for example is formatted in JSON, which is both

human readable and easily consumed by calling applications.


There are quite a few standard command line tools available to control SAP Web Dispatcher, both locally and remotely. However, the most powerful tools that offer the most comprehensive set of features work only in an interactive mode, such as wdispmon and the Web Admin Interface. That is why I decided to write wdcontrol, which connects to the Web Admin Interface and could eventually provide the same functionality in the command line. So far, the program is a first version with a limited set of commands. New commands can be added on demand.

Further Reading