12 Using the 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>

#define NETBUFLEN 1024

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");

	
    CegoNet *pCegoNet = new CegoNet( logFile, logMode );	
    pCegoNet->connect(serverName, portNo, tableSet, user, password);

    ...
Please note, that the NETBUFLEN value is an initial value for the network buffer. If required, the network buffer is increased to an appropriate value ( if larger messages have to be sent or are expected ).

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);
    ...

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 )
~CegoNet()
void connect(const Chain& serverName, int port, const Chain& tableSet, const Chain& user, const Chain& pwd)
long doQuery(const Chain& query)
bool fetchData(const ListT<CegoField>& schema, ListT<CegoField>& fvl)
void disconnect()
bool isFetchablet()
bool abortQuery()
bool resetQuery()
long getAffected()
void getSchema(ListT<CegoField>& schema)
void getProcResult(ListT<CegoProcVar>& outParamList, CegoFieldValue& retValue)

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