BdsApi Documentation

Author

Dr Terry Barnaby

Version

2.0.11

Date

2013-12-02

Introduction

This document covers the BEAM BdsApi software API for the Blacknest Data System. This API provides the ability to access data and administer the BDS system. The API is an object orientated API implemented in 'C++' with a number of object classes. The API operates over a network type interface using an RPC type mechanism.

The BdsApi API makes use of the BEAM 'C++' class library. The BEAM 'C++' class library provides a small set of low level 'C++' classes for strings, lists and system interface functions. It also implements the BOAP RPC mechanism used to implement the BdsApi. There is some brief information on the BEAM class library later on in this page and a full API definition is available in the libBeam documentation.

Overview

Generally users of the system are only concerned with the DataAccess API.

The BdsApi has been developed using the BOAP (BEAM Object Access Protocol). This provides a simple but powerful Object Orientated RPC mechanism. The BdsApi is written in a high level interface definition language (IDL). The bidl tool generates the client and server side 'C++' interface and implementation files for the API. These are then provided as a set of 'C++' header files and a binary library file for the clients to link to. The BOAP system employs a simple BOAP name server process that provides a translation between object names and IPAddress/Socket numbers. The BOAP name server runs on the BDS Controller. More information on the BOAP system can be found in the libBeam documentation.

THE BDS API implements a number of data storage classes and three interface objects. The interface objects are:

1. Bds::DataAccess BDS Data API: This will provide read only access to the data and meta data. It will be used by the AutoDRM email and Web systems as well as for program access to the data.
2. Bds::DataAddAccess BDS DataAdd API: This will provide read and restricted write access to enable the adding of data to the system. It will not allow deletions of data to be performed. It is designed to be used by manual and automatic data adding programs.
3. Bds::AdminAccess BDS Admin API: This will provide full read/write access to the data and meta data as well as administrative configuration information.

Examples

There are some examples of client applications using the BdsApi in the bdsExamples directory of the source code. Some simple Data Access client examples are listed below:

/*******************************************************************************
 *      BdsDataClient1.cpp      BDS API example code for a Data Client
 *                              T.Barnaby,      BEAM Ltd,       2008-09-02
 *******************************************************************************
 *
 *      This is a very basic example of using the BdsApi from a data access
 *      perspective. It is designed to give an overview of using the API.
 *      This program gets data in the BKNAS format.
 */
#include <iostream>
#include <stdio.h>
#include <BdsD.h>
#include <BdsC.h>

using namespace Bds;
using namespace std;


// Function to read some data
BError bdsTest(DataAccess& bds){
        BError                  err;
        Selection               selection;
        DataInfo                dataInfo;
        DataHandle              dataHandle;
        BArray<BUInt8>          data;
        
        // Set up selection
#ifndef ZAP
        selection.startTime.setString("2002-01-01T00:00:00.000000");
        selection.endTime.setString("2002-01-01T00:01:00.000000");
#else
        selection.startTime.setString("2002-01-01T23:59:00.000000");
        selection.endTime.setString("2002-01-02T00:01:00.000000");
#endif
        selection.channels.append(SelectionChannel("BN", "EKA", "", ""));

        // Get list of all data available for the selection             
        if(err = bds.dataSearch(selection, dataInfo)){
                return err.set(1, BString("Error: Searching for data: ") + err.getString());
        }

        // We should now choose which set of data we would like from the list, here we just
        // choose the first entry and get the data in appropriate format.
        if(!dataInfo.channels.size())
                return err.set(1, "No data found");
        
        if(err = bds.dataOpen(dataInfo, "r", "IMS", 0, dataHandle)){
                return err;
        }
        
        while(1){
                if(err = bds.dataFormattedRead(dataHandle, 1024, data)){
                        return err;
                }

                if(data.size() == 0)
                        break;
                
                fwrite(data.data(), 1, data.size(), stdout);
        }
        
        return err;
}

int main(int argc, char** argv){
        BError                  err;
        BString                 hostName;
        DataAccess              bds;

        hostName = getenv("BDS_HOST");
        if(hostName == "")
                hostName = "localhost";
        
        if(argc == 2)
                hostName = argv[1];

        // Connect to the DataAccess service
        if(err = bds.connectService(BString("//") + hostName + "/bdsDataAccess")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }

        // Connect to service
        if(!err)
                err = bds.connect("test", "beam00");
        
        // Run a normal data gathering as a normal data access client would.
        if(!err)
                err = bdsTest(bds);
        
        if(err){        
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
                
        return 0;
}

/*******************************************************************************
 *      BdsDataClient2.cpp      BDS API example code for a Data Client
 *                              T.Barnaby,      BEAM Ltd,       2008-09-02
 *******************************************************************************
 *
 *      This is a very basic example of using the BdsApi from a data access
 *      perspective. It is designed to give an overview of using the API.
 *      This program gets data in raw format and outputs it in ASCII.
 */
#include <iostream>
#include <iomanip>
#include <stdio.h>
#include <BdsD.h>
#include <BdsC.h>

using namespace Bds;
using namespace std;


// Function to read some data
BError bdsTest(DataAccess& bds){
        BError                  err;
        Selection               selection;
        DataInfo                dataInfo;
        DataHandle              dataHandle;
        DataBlock               data;
        BUInt32                 blockNumber = 0;
        BUInt                   c;
        BUInt                   s;
        
        // Set up selection
        selection.startTime.setString("2008-01-03T00:00:00.000000");
        selection.endTime.setString("2008-01-03T00:01:00.000000");
        selection.channels.append(SelectionChannel("BN", "EKA", "", ""));

        // Get list of all data available for the selection             
        if(err = bds.dataSearch(selection, dataInfo)){
                return err.set(1, BString("Error: Searching for data: ") + err.getString());
        }

        // We should now choose which set of data we would like from the list, here we just
        // choose the first entry and get the data in appropriate format.
        if(!dataInfo.channels.size())
                return err.set(1, "No data found");
        
        if(err = bds.dataOpen(dataInfo, "r", "API", 0, dataHandle)){
                return err;
        }
        
        while(1){
                if(err = bds.dataGetBlock(dataHandle, 0, 0, blockNumber, data)){
                        return err;
                }
                
                if(data.startTime >= dataInfo.endTime)
                        break;

                for(s = 0; s < data.channelData[0].size(); s++){
                        for(c = 0; c < data.channelData.size(); c++){
                                if(c != 0)
                                        std::cout << ", ";
                                std::cout << setw(8) << data.channelData[c][s];
                        }
                        std::cout << "\n";
                }
                blockNumber++;
        }
        
        return err;
}

int main(int argc, char** argv){
        BError                  err;
        BString                 hostName;
        DataAccess              bds;

        hostName = getenv("BDS_HOST");
        if(hostName == "")
                hostName = "localhost";
        
        if(argc == 2)
                hostName = argv[1];

        // Connect to the DataAccess service
        if(err = bds.connectService(BString("//") + hostName + "/bdsDataAccess")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
        
        // Connect to service
        if(!err)
                err = bds.connect("test", "beam00");
        
        // Run a normal data gathering as a normal data access client would.
        if(!err)
                err = bdsTest(bds);
        
        if(err){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
                
        return 0;
}

/*******************************************************************************
 *      BdsDataClient3.cpp      BDS API example code for a Data Client
 *                              T.Barnaby,      BEAM Ltd,       2008-09-02
 *******************************************************************************
 *
 *      This is a very basic example of using the BdsApi from a data access
 *      perspective. It is designed to give an overview of using the API.
 *      This program gets information on the data channels.
 */
#include <iostream>
#include <iomanip>
#include <stdio.h>
#include <BdsD.h>
#include <BdsC.h>

using namespace Bds;
using namespace std;


// Function to read some data
BError bdsTest(DataAccess& bds){
        BError                  err;
        Selection               selection;
        DataInfo                dataInfo;
        ChannelInfos            channelInfos;
        BIter                   i;
        BUInt                   c;
        
        // Set up selection
        selection.startTime.setString("2008-01-03T00:00:00.000000");
        selection.endTime.setString("2008-01-03T00:01:00.000000");
        selection.channels.append(SelectionChannel("BN", "EKA", "", ""));

        // Get list of all data available for the selection             
        if(err = bds.dataSearch(selection, dataInfo)){
                return err.set(1, BString("Error: Searching for data: ") + err.getString());
        }

        // We should now choose which set of data we would like from the list, here we just
        // choose the first entry and get the data in appropriate format.
        if(!dataInfo.channels.size())
                return err.set(1, "No data found");
        
        if(err = bds.dataGetChannelInfo(dataInfo, channelInfos)){
                return err;
        }

        // This displays some of the information available      
        for(c = 0; c < channelInfos.channels.size(); c++){
                ChannelInfo&    ci = channelInfos.channels[c][0];
                
                cout << (c + 1) << ": Station: " << ci.station.name << " Channel: " << ci.channel.channel << "\n";
                cout << "    " << "Calibration: " << ci.calibration.calibrationFactor << " Frequency: " << ci.calibration.calibrationFrequency <<
                        " Units: " << ci.calibration.calibrationUnits << "\n";
                cout << "    " << "Instrument: " << ci.digitiser.name << "\n";
        }
        
        
        return err;
}

int main(int argc, char** argv){
        BError                  err;
        BString                 hostName;
        DataAccess              bds;

        hostName = getenv("BDS_HOST");
        if(hostName == "")
                hostName = "localhost";
        
        if(argc == 2)
                hostName = argv[1];

        // Connect to the DataAccess service
        if(err = bds.connectService(BString("//") + hostName + "/bdsDataAccess")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
        
        // Connect to service
        if(!err)
                err = bds.connect("test", "beam00");
        
        // Run a normal data gathering as a normal data access client would.
        if(!err)
                err = bdsTest(bds);
        
        if(err){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
                
        return 0;
}