Skip to Content
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)
     ICMGetThreadList
     ICMGetConnectionList
     ICMGetConnectionList2
     ICMGetProxyConnectionList
     ICMGetCacheEntries
     ICMGetAllCacheEntries
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.
SYNOPSIS
    sapcontrol [-prot <protocol>]
               [-trace <filename>]
               [-debug]
               [-user <user> <password>]
               [-queryuser]
               [-repeat <N> <D>]
               [-format <format>]
               [-host <hostname>]
               -nr <instance number>
               -function <webmethod> [parameter list]
DESCRIPTION
    Control and monitor SAP instances via WebService interface of SAP Start Service.
OPTIONS
    -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
    -debug
        Write local trace to stderr
    -user <user> <password>
        OS user and password for Webservice authentication
    -queryuser
        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.
StopService
Stops the start service, but not the Web Dispatcher instance.
RestartService
StartSystem
A Web Dispatcher system usually consists of only one instance, so this command is equivalent to InstanceStart.
StopSystem
Usually equivalent to InstanceStop.
RestartSystem
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>]
GetProcessList
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.
GetVersionInfo
Determines release and patch level for Web Dispatcher and Start Service.
GetEnvironment
Prints a list of the environment variables used by the Web Dispatcher system.
GetStartProfile
Prints the start profile that is used by the start service.
ParameterValue [<parameter>]
Prints a list of all profile parameters or one specific parameter.
GetAccessPointList
Prints a list of access points (ports), including those of the start service.
GetQueueStatistic
Prints request queue statistics (peak, max).
ICMGetThreadList
Prints the status of all sapwebdisp threads, including the main thread, watchdog thread, and worker threads.
ICMGetConnectionList
Prints a list of current front-end connections. (This does not include the connections to the back-end application servers.)
ICMGetCacheEntries
Prints a list of cached entries (in case the Web Dispatcher has an active cache handler.)
WebDispGetServerList
Prints a list of back-end application servers.
ListDeveloperTraces
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.
ABAPReadSyslog
Prints the content of the SYSLOG.
ABAPReadRawSyslog
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.
wdcontrol
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: https://github.com/wtobia/wdcontrol
usage: wdcontrol.py [-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 (wdcontrol.py -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.host”: “my.wd.host.com”,
  “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:

{
  “node.name”: “J2EE3565100”,
  “node.stack”: “J2EE”,
  “system.id”: “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:

    wdcontrol.py DEV_J2EE3565100.wdc –command isNodeActive

    All other commands that are not related to a specific instance can skip the configuration file. Examples:

    wdcontrol.py –command refresh
    wdcontrol.py –commmand isPortActive –port 8000

List of currently supported commands:
command description
info

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.

Summary

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

To report this post you need to login first.

2 Comments

You must be Logged on to comment or reply to a post.

  1. Andy Silvey

    Hi Tobias,

    that’s an interesting blog.

    We’ve written our own scripts for the simplest tasks of stopping and starting WebDispatchers but still use the Web Interface for removing Instances etc.

    Thanks,

    Andy.

    (0) 

Leave a Reply