This document describes how Web services based on the use of XML/SOAP can be used to provide Data Base facilities
for a range of Data Acquisition Applications.
The server is normally a Httpd task which contains software to implement the Data Base 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 Base software.
The software structure is summarised via this diagram.
The following access methods are available.
| nodes |
|---|
| get |
| set |
| delete |
| types |
| values |
| GetLastError |
|---|
| GetInformation |
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.
The DataBase service provides a general set of operations for manipulating a simple database suitable for storing parameters, settings and options within a Data Acquisition environment.
nodeName is the name of a database node. Database nodes must have one of the following forms;
rootname/nodepath
rootname
The rootname component must be one of EXPERIMENTS, CONFIGURATIONS, CURRENT_EXPERIMENT, CURRENT_CONFIGURATION.
The nodepath component can be one or more database nodes separated by backslash (/) characters.
NOTE: Both / and \ are supported by the server code as separators but only / currently works when using the HTML interface.
[\ is an escape character and so causes complications]
Where an operation parameter is optional then the parameter can be supplied as either a null string or the string NULL, both of which are taken to indicate that the parameter is not supplied.
Available operations are:
nodes nodeName ?pattern?
If pattern is not specified, the command returns a list of names of all the subnodes of nodeName. If pattern is specified, only those names matching pattern are returned. If the specified nodeName does not exist or cannot be accessed, then an error is generated.
get nodeName valueName
Returns the data associated with the value valueName. If either the node or the value does not exist, then an error is generated. For more details on the format of the returned data, see DATA TYPES below.
set nodeName ?valueName data ?type??
If valueName is not specified, creates the node nodeName if it does not already exist. If valueName is specified, creates the node nodeName and the value valueName if necessary. The contents of valueName are set to data with the type indicated by type. If type is not specified, the type string is assumed. For more details on the data and type arguments, see DATA TYPES below.
delete nodeName ?valueName?
If valueName is specified, the specified value under nodeName will be deleted from the database. If valueName is specified, the specified node and any subnodes or values beneath it in the database hierarchy will be deleted. If the node could not be deleted then an error is generated. If the nodes does not exist, the operation has no effect.
type nodeName valueName
Returns the type of the value valueName in the node nodeName For more information on the possible types, see DATA TYPES below.
values nodeName ?pattern?
If pattern is not specified, returns a list of all the values in nodeName. If pattern is specified, only those names matching pattern are returned.
Each value under a node in the database contains some data of a particular type in a type-specific representation. The database service converts between this internal presentation and one that can be carried by the SOAP/XML transport.
The following types are recognized by the data base service:
binary:
The data base value contains arbitary binary data
string:
The data base value contains a null-terminated string
multi_string:
The data base value contains an array of null-terminated strings
long (dword32):
The data base value contains a little-endian 32-bit number
short (dword16):
The data base value contains a little-endian 16-bit number
long_big_endian (dword32):
The data base value contains a big-endian 32-bit number
short_big_endian (dword16):
The data base value contains a big-endian 16-bit number
Other data types (such as floating point data) are for future consideration.
Taking as an example the threshold for ADC 0 in a CAEN V785 VME module
The node name could have the general format
EXPERIMENTS/experiment id/run id/Setup/date id/VME/module
so as an example
nodeName is EXPERIMENTS/agata_e103/run20/Setup/Jun2010_08/VME/V785#2
valueName is Threshold0
the data type held in the data base node is string which contains the value 16
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.
int nodes (char* nodeName, char* pattern, int *rc, char* result);
int get (char* nodeName, char* valueName, int *rc, char* result);
int set (char* nodeName, char* valueName, char* data, char* type, int *rc);
int delete (char* nodeName, char* valueName, int *rc);
int type (char* nodeName, char* valueName, int *rc, char* result);
int values (char* nodeName, char* pattern, int *rc, char* result);
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.
int GetLastError (int *rc, int *code, char *reason);
int GetInformation (int *rc, char *reason);
A software package is available which uses TclHttpd to implement a demonstration of the Data Base Service. This can be downloaded from the NPG server.
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. June 24 2009
