Difference between revisions of "OpenDBX/C++ API/Usage"

Revision as of 00:08, 12 March 2009

Using the C++ interface is fairly easy and pretty straight forward: Connect to your database, send your query, retrieve the result set and process the row values. After you've done that you can continue to send queries. Cleaning up is done automatically if you don't decide otherwise.

A simple test program might be:

#include <opendbx/api>
#include <iostream>

using namespace OpenDBX;

int main( int argc, char* argv[] )
{
    try
    {
        Conn db = Conn( "mysql", "127.0.0.1", "" );
        std::cout << "Initialized connection" << std::endl;
    }
    catch( std::exception &e )
    {
        std::cerr << "Caught exception: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

As soon as you've implemented something you want to test, you want compile and run your program to see if it is successful. Compilation and linking of your program are done with

g++ -o myprog myprog.cpp -lopendbxplus

This call the GNU C++ compiler and translates the C++ code in "myprog.cpp" into an binary object called "myprog.o". In the second step it creates an executable named "myprog" and links it against the OpenDBX library ("-lopendbxplus"). Now you can test and see what happens.

Dealing with connections

Using the API starts with establishing a connection to the database server by creating an instance of the Conn class with the parameters backend, host and port, e.g.

Conn db = Conn( "mysql", "localhost", "3306" );

The first parameter is the name of the database backend that should be used for connecting to the database server. Possible values for this parameter as well as hints for the other parameters (which depend on the used backend) are availabe at the configuration page.

Handling options and capabilities

If you want to check for library info or use non-standard options like encrypted data transfer or multi-statement support (provided they are supported), this can be changed after calling Conn::getOption() or Conn::setOption](). Conn::getOption() returns info about the library and its implemented functionality while Conn::setOption() can change the default behavior of the library. The options must be changed before authenticating the connection with the Conn::bind() method to have any effect.

int safe;
int option = ODBX_TLS_ALWAYS;

db.getOption( ODBX_OPT_THREAD_SAFE, (void*) &safe );
db.setOption( ODBX_OPT_TLS, (void*) &option );

Capabilities are implemented sets of functions serving a specific purpose, e.g. handling large objects. By calling Conn::getCapabilities() you can find out what sets of functionality are supported by the backend. You can do this any time after successfully creating a connection object with was initialized with at least the backend parameter. Each set - the basic set is only the default one which is always available - is fully implemented by the backend, so you don't have to worry that the one or another function might be missing.

bool use_lo = false;

if( db.getCapabilites( ODBX_CAP_LO ) ) {
    use_lo = true;
}

Executing statements

The Conn::create() method creates and initializes a new statement instance from a SQL string. Currently, there are only simple statement objects implemented, which needs to be complete statements which can be sent to the database with Stmt::execute(). This method returns a Result object encapsulating one or more result sets returned by the database depending on the statement sent.

Retrieving results

Each result set must be retrieved using Result::getResult(), while Result::getRows() fetches a row from the current result set if the statement was a SELECT like statement. Otherwise, Result::rowsAffected() can be used to get the number of rows that were touched by the statement. If the statement may return rows, the Result::columnName() and Result::columnType() methods are able to provide some informations about the columns indexed from 0 to n. It's also possible to map the column name with the Result::columnPos() method to the column index which is required be the other column methods. To get the actual value and length of the content in the current row at the given position, the Result::fieldValue() and Result::fieldLength() must be called.

Using large objects

In case the unterlying database library requires special handling of large objects (binary or text LOBs), the value of Result::fieldValue() has to be feed into the Result::getLob() method. It returns a Lob object which enables the application to read from and write to a large object using Lob::read() respectively Lob::write(). This is only necessary if the Conn::getCapability() method returns true when asking for ODBX_CAP_LO.

Error handling

If an error occurs in any of the object methods, the objects will throw an instance of the Exception class with extends the runtime_error exception of the STL. The instance contains an error message, the OpenDBX error code and an error type indicating the severity of the error. This information can be retrieved by the methods Exception::what(), Exception::getCode() and Exception::getType().

Further examples

A full-featured working example of how to use the OpenDBX C++ API correctly can be found in the test/odbxplus-regression.cpp file of the source distribution available at the download section.