12 Using the CegoNet C++ API

Back to TOC

For an application programmer, it may be useful to access the cego database with a more low level programming interface. For those guys, cego provides a C++ programming interface.

To use the C++ API, you should have compiled and installed the base library, the xml library and the cego client library. All packages are available as opensource at www.lemke-it.com. Please refer to the README information of each package, how to compile and install it.

12.1 Connecting to the database

The first thing, you have to do in you application program is to connect to the cego database daemon. For this, you can use the following code. 

/* from base */ 
#include <Chain.h>
#include <Logger.h>
#include <Exception.h>
#include <Net.h>
#include <NetHandler.h>

main(int argc, char **argv)
{	

    Chain serverName("myServer");
    int portNo = 2200;

    Chain tableSet("TS1");
    Chain user("lemke");
    Chain password("lemke");
    Chain logFile("cg.log");
    Chain logMode("notice");

    CegoDbHandler::ProtocolType protType = CegoDbHandler::SERIAL;
	
    CegoNet *pCegoNet = new CegoNet(protType, logFile, logMode );	
    pCegoNet->connect(serverName, portNo, tableSet, user, password);

    ...

12.2 Executing a query

If a connection has been set up and a database session bas been started, any kind of database queries can be executed. 
  
    // define any needful sql query here
    Chain stmt("insert into ....");

    try
    {
       long res = _pCegoNet->doQuery(stmt);
    }
    catch ( Exception e )
    {
	Chain msg;
        e.pop(msg);
        cout << "Error : " << msg << endl;
    }
Based on the kind of database query, which has been sent, a different result code is returned. For any kind of modifying queries without any data return (insert, update, delete ), the database handler returns DB_OK if the query could be executed successful. Otherwise DB_ERROR is returned.

For queries, returning any kind of user data, please see the following sections.

12.3 Fetching data 


    ...
    ListT<CegoField> schema;
    pCegoNet->getSchema(schema);
	
    ListT<CegoField> fvl;
    while ( pCegoNet->fetchData(schema, fvl)  )
    {
        CegoField *pF = fvl.First();
	while ( pF ) 
	{
	    cout << pF->getValue() << "\t";
	    pF = fvl.Next();
	}
	cout << endl;
	    
	fvl.Empty();
    }
    ...

12.4 Retrieving query results

The amount of affected rows for modifying queries ( e.g. insert, update, delete ) can be retrieved with the return value of the doQuery method 

  ...
  Chain stmt("update t1 set b = 24 where a = 11;");
  long res = _pCegoNet->doQuery(stmt);
  ...
To retrieve stored procedure results, the getProcResult method can be used. This method provides the return code of the any function call but also out param values. 
    ...  
    Chain stmt(":p1 = call myProc( 23, :p2 )");

    int res = _pCegoNet->doQuery(stmt);

    ListT outParamList;
    CegoFieldValue retValue;
    pCegoNet->getProcResult(outParamList, retValue);
    ...
If the database handle is not used anymore, the connection can be closed and the handle can be deleted. 
    ...
    pCegoNet->disconnect();
    delete pCegoNet;

12.5 Class reference

In the following a description is given for all cego classes, which might be used for a client application program.

12.5.1 CegoNet

The following methods of CegoNet are recommended to be used in client programs
CegoNet
Method Description
CegoNet( const Chain& logFile, const Chain& logMode) Constructor for the database handle.The given arguments are the logfile, which should be writable and the required logmode. Valid logmodes are either "notice", "error" or "debug"
~CegoNet() Destructor for the database handle
void connect(const Chain& serverName, int port, const Chain& tableSet, const Chain& user, const Chain& pwd) Connect method with the required connection parameters
long doQuery(const Chain& query)Executing any query. For some queries, the return value given information about affected tuples (e.g. update or delete )
bool fetchData(const ListT<CegoField>& schema, ListT<CegoField>& fvl)IF te hanlde is fetchable, this method retrieves the next available tuple. The schema should be set up for the required attribute values which should be achieved
void disconnect()
bool isFetchable()The handle can be checked out, if further data can be fetched.
bool abortQuery()The current query can be aborted
bool resetQuery()The current query can be reset to the first result tuple
long getAffected()Returns the number of affected rows
void getSchema(ListT<CegoField>& schema)Returns the complete result schema of the requested query
void getProcResult(ListT<CegoProcVar>& outParamList, CegoFieldValue& retValue)Returns the out parameter for a requested procedure call

12.5.2 CegoField

The following methods of CegoField are recommended to be used in client programs
CegoField
Method Description
bool isNullable() const
const Chain& getTableName() const
const Chain& getTableAlias() const
const Chain& getAttrName() const
CegoFieldValue& getFieldValue()
Chain toChain() const
friend ostream& operator << (ostream& s, const CegoField& f)

12.5.3 CegoFieldValue

The following methods of CegoField are recommended to be used in client programs
CegoFieldValue
Method Description
const CegoDataType getType() const
void* getValue() const
int getLength() const
Chain toChain() const
Chain valAsChain() const

12.5.4 CegoProcVar

The following methods of CegoProcVar are recommended to be used in client programs
CegoFieldValue
Method Description
const Chain& getName() const
const CegoFieldValue& getValue() const