BdsApi
1.2.10
|
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.
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:
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; }