MIDAS - The Multiple Instance Data Acquisition System

Data Acquisition Control using XML/SOAP protocols

(1) Introduction

This document describes how Web services based on the use of XML/SOAP can be used to provide Run Control facilities for a range of Data Acquisition Applications.
The server is normally a Httpd task which contains software to implement the Data Acquisition Control functions. The user interacts either via a Web Browser which uses Html and JavaScript to communicate with client software within the Httpd task or via a GUI Client Application which uses SOAP messages to communicate directly with the Data Acquisition Control software. The software structure is summarised via this diagram.
The procedures made available via the SOAP protocol allow for control of the software state machine within the Data Acquisition System and for monitoring the current state.

(2) Client

The following control procedures are available.

The following information procedures are available.

These procedures are defined via the Service WSDL file (which is the preferred way for a Web service to publish its documentation) and which can be converted using packages such as gSOAP into C and/or C++ code segments.

(3) Software State Machine

The Software State Machine is summarised via this diagram.

The State Machine codes are:

When a command is received the Httpd server will respond quickly (within 500 msecs) and so the client (which is often a component of the GUI) does not have to worry about being held for long periods of time or for interactive timeouts expiring. In many cases the command will take much longer than this to execute and for this reason "transitory" states are defined.
When the server receives a GO command as long as the current state is Stopped (state=0) this is a valid request. The server may respond to the client with changing to going (state=4). The system state will then change to either Going (state=1) or Error (state=6) when the command completes execution. The client can use the GetState command to monitor the server.

State Machine Transitions are:

The command OPTION is provided as a general purpose way for options or additional application specific information to be passed to the Data Acquisition Applications. The DoOption procedure has a string argument which is used to pass the additional information. The format of this string is Application dependent. The procedure can be issued at any time. The server may move to the transitory state executing while the Application is executing the command. On completion the server will either return to the state it was in prior to executing the command or to Error. The GetOption procedure passes a string argument on request and received a string argument on response.

(4) Client API procedures

The procedure examples are "pseudo-code". The actual code will be dependent on the SOAP support library used.

For all procedures the response rc is an integer which has the value 0 in the case that the command is executed without error by the server.
All errors are indicated by a non zero response code.
    = 1   the system is currently in the wrong state for the command.

int DoReset (char *parameter, int *rc);
int DoSetUp (char *parameter, int *rc);
int DoStop (char *parameter, int *rc);
int DoGo (char *parameter, int *rc);
int DoOption (char *parameter, int *rc);

These procedures cause the corresponding command to be executed within the Data Acquisition System. The format of the calling string argument is application dependent.

int GetOption (char *parameter, int *rc, char *options);
int GetState (int *rc, int *code, char *state, char *reason);
int GetCounters (int *rc, char *counters);
int GetRates (int *rc, char *rates);

The GetState procedure allows the current state of the Data Acquisition System to be obtained.
code is the "State Machine Code" and reason the corresponding meaning as listed in section 3.

The GetCounters procedure returns a string containing a number of useful software counters. The number and meaning will be application dependent. Typical counters would be the "Number of Events Detected" and "Number of Data Blocks Processed".

The GetRates procedure returns a string containing a number of useful software rates. Typically these would be the rates associated with the counters.

The GetOption procedure returns a string which has an application dependent format. Typically this could be used to read back options defined by the DoOption procedure.

int GetLastError (int *rc, int *code, char *reason);
int GetInformation (int *rc, char *reason);

In the event of a procedure returning a non zero response (ie rc != 0) then further information about the error can be obtained using these procedures.

A software package is available which uses TclHttpd to implement a demonstration of the Run Control Service. This can be downloaded from the NPG server.
The package provides a Httpd server which can be used to test client implementations. The software can be run using either a Windows or Linux PC.

Download the file which is in tar.gz format and is of size 4205310 bytes.

Linux: Create a directory RunControlDemo and make this your current directory. Use tar -z -x -f to extract the downloaded archive into the current directory. Set the environment variable MIDASBASE to the full pathname of the directory RunControlDemo. From the directory RunControlDemo run the command TclHttpd/Linux/TclHttpd-server. You should see output like

can't find package limit
Running with default file descriptor limit
/debug user "debug" password "ivms072etd 1"
httpd started on port 8015

Cannot use /tmp/RunControlDemo/config/TclHttpd/nnsv/startup.tcl
Cannot use /tmp/RunControlDemo/config/TclHttpd/localhost/startup.tcl
/DataBaseAccessServer
Message Logger using /tmp/RunControlDemo/log
/MessageLoggerServer
/DataAcquisitionControlServer
Completed custom startup from /tmp/RunControlDemo/config/TclHttpd/startup.tcl

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns:Get-State xmlns:ns="urn:DataAcquisitionControlServer"></ns:Get-State>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body xmlns:ns="urn:DataAcquisitionControlServer" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns:Get-StateResponse>
<Code xsi:type="xsd:int">0</Code>
<State xsi:type="xsd:string">2</State>
<Reason xsi:type="xsd:string">reset</Reason>
</ns:Get-StateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Windows: Use winzip to extract the archive into an empty directory. In the directory you will now find a Windows ShortCut. This was created when the directory RunControlDemo was in d:\ and so its properties will need to be changed to the location on your disc. Double click on the shortcut to start the server.
The Httpd server will run in a command prompt window and the output will be similar to that for Linux.
The software assumes that a directory C:\Temp exists and can be written to. (Vista users take note!).
For Windows XP and Vista (or any system with firewall software installed) you will have to give the software permission to access the network.

The Demo server simulates the expected state changes of a real Data Acquisition system including errors. [Every 5th request to the GO method will generate an error condition!].

The Demo server now implements version 2 of the protocol. The parameter strings for RESET; SETUP; GO; STOP etc (Command); for Set Option and for Get Option can be supplied. Terminate the parameter string with a RETURN. To Set an Option then click on the "Set Option" button. A click on the "Get Option" button will read back the Option string and display as an alert message.

Version 2.0 V Pucknell, STFC, Daresbury Lab.   March 17 2009