MIDAS - The Multiple Instance Data Acquisition System

Message Logger using XML/SOAP protocols

(1) Introduction

This document describes how Web services based on the use of XML/SOAP can be used to provide a simple Message Logger facility for a range of Data Acquisition Applications.
The server is normally a Httpd task which contains software to implement the MessageLogger 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 MessageLogger software.
The server uses ELOG for archive of permanent messages. The software structure is summarised via this diagram.

(2) Client

The following access method is available.

The following information methods 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) Description

The MessageLogger service provides a simple method for defining messages containing routine logging, exception reporting and diagnostic information within a Data Acquisition environment.

The DefineMessage method allows for 3 attributes (strings) to be provided for the message.
One of these, source, is used to identify the origin of the message and is normally provided automatically by the API interface. If it is a null string or the string NULL then the server will insert the message source from available network identification.
The attribute class is used to identify the application generating the message and the attribute level the degree of priority or importance of the message.
These 3 attributes are used to determine if the message should be passed on to the ELOG server and are used as attributes for the message by ELOG.

class may have one of the following values;

Other values will no doubt be defined in the future.

level should have one of the following values;

ZERO is the least important and CATASTROPHE the most important message level.

(4) Client API procedures

The procedure prototypes are simply examples. The actual code will be dependent on the SOAP support library used.
These examples are in fact taken from a definition file which can be used by gSOAP.

For all procedures the response ResponseCode 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.

int ns__DefineMessage(char *class_, char *level, char *source, char *message, int *ResponseCode);

int ns__Get_LastError(struct ns__Get_LastErrorResponse{int *ResponseCode; int *Code; char *Reason;} *r);

int ns__Get_Information(struct ns__Get_InformationResponse{int *ResponseCode; char *Reason;} *r);

In the event of the DefineMessage procedure returning a non zero response (ie ResponseCode != 0) then further information about the error can be obtained using the Get-LastError and Get-Information procedures.

(5) gSOAP Implementation

This section was written using gSOAP 2.7.11; 32 bit Linux; C code and gcc 4.1.1. Other packages, versions and bindings may perform in a different way. (For example gSOAP 2.7.11 does not make for SunOS using my compiler).

The recommended start point for a client of an existing service is to use the provided WSDL file. This file describes the SOAP protocol used by a service in a system and implementation independent manner. The format of the API interface is not defined by the WSDL file and the software package (such as gSOAP) used to generate the specific API interface is free to use whatever format it chooses as long as in use the correct XML is generated and the server response handled correctly.

If the WSDL file is not available, for example when building a new service then other methods may be used. For example gSOAP can use a definition file as a start point.
The gSOAP definition file (MessageLoggerServer.def) for the MessageLoggerServer client is

//gsoap ns service name:         MessageLoggerServer
//gsoap ns service style:        rpc
//gsoap ns service encoding:     encoded
//gsoap ns service namespace:    http://npg.dl.ac.uk:8015/MessageLoggerServer.wsdl
//gsoap ns service location:     http://npg.dl.ac.uk:8015/MessageLoggerServer
//gsoap ns schema namespace:     urn:MessageLoggerServer
int ns__DefineMessage(char *class_, char *level, char *source, char *message, int *ResponseCode);
int ns__Get_LastError(struct ns__Get_LastErrorResponse{int *ResponseCode; int *Code; char *Reason;} *r);
int ns__Get_Information(struct ns__Get_InformationResponse{int *ResponseCode; char *Reason;} *r);

This definition file can be converted into the Web Service Description file (WSDL) which is the preferred way for a Web service to publish its documentation.
This can be done using the gSOAP program soapcpp2.

soapcpp2 -C -c -x MessageLoggerServer.def

If you are starting from the WSDL file then gSOAP can convert this into a C code header file by

wsdl2h -c MessageLoggerServer.wsdl

which creates the file MessageLoggerServer.h
Next use soapcpp2 to create the C code client stubs and header files

soapcpp2  -C -c -x -w -L -t -I $(SOAPBASE)\import MessageLoggerServer.h

which creates the files soapStub.h, soapH.h, soapC.c, soapClient.c and MessageLoggerServer.nsmap

If you are starting from the def file then you can use this directly

soapcpp2  -C -c -x -w -L -t -I $(SOAPBASE)\import MessageLoggerServer.def

A software package is available (for Linux) which shows how a standalone command line program DefineMessage can be built using gSOAP to send messages to the server (see below). You can obtain it from the NPG server.
DefineMessage.c is the program and handles the command line arguments; MessageLoggerServer.c is the source of a dynamic load library which defines a API interface MessageLoggerServer__DefineMessage and uses the gSOAP procedures to give the library libMessageLoggerServer.so. You will need to install gSOAP.
The software download contains the software pre-built for 32 bit Linux. Use the server in the RunControlDemo below. Set the environment variable MessageLoggerServerHost to the location of your server.
The command DefineMessage "hello world" will then define a message in the server.
Hint - to test the error response make the server log directory read only!

A software package is available which uses TclHttpd to implement a demonstration of the MessageLogger Service. It can be downloaded from the NPG server.
In this release the Httpd server only writes messages to a local disc file. Interaction with ELOG is under development.
The environment variable MessageLoggerBase can be used to define the location of the directory (which must exist) used by the server for storing messages. By default the directory log in the installation directory is used.
This package also contains the demonstration of the Run Control Service and the Data Base Service
For installation instructions see the Run Control page.

You can check the server by using a Web Browser and connect to http://localhost:8015 (or appropiate if the browser is running in a remote system). The browser window looks like this.

Version 1.1 V Pucknell, STFC, Daresbury Lab.   July 30 2008