qdb_connect()

Connect to a database

Synopsis:

#include <qdb/qdb.h>

qdb_hdl_t   *qdb_connect( const char *dbname,
                          int flags );

Arguments:

dbname
The database device name (for example, /dev/qdb/customerdb).
flags
Flags which can be used to control attributes of the connection. This argument can be 0, or a combination of:

Library:

qdb

Description:

This function connects to the database specified by dbname, and returns a pointer to the database connection. You need to call this function for every database, or for concurrent access to one database.


Note: Two threads can share the same database connection, provided they coordinate between themselves. Alternatively, each thread can call qdb_connect() and have its own connection.

You should disconnect all connections with a call to qdb_disconnect() when you're finished using them.

Using asynchronous mode

By default, QDB completes execution of statements against a database before returning from qdb_statement(). However, you can connect to QDB using asynchronous mode by setting the QDB_CONN_STMT_ASYNC in flags.

While some errors (such as syntax errors) can be caught before qdb_statement() returns in this mode, others, such as database constraint violations, may not be generated until the statement is completed. These errors are available only to a subsequent qdb_getresult() call.

The advantage of asynchronous operation is that it allows parallelism between the client application and the database engine, especially in cases where the client will later retrieve the statement result anyway (for example, SELECT statements). The danger of asynchronous operation is that the client must be aware that the statement may not necessarily have completed or indicated all errors, and must be coded to call qdb_getresult() to retrieve any errors.

The mode you should use depends on the type of operation you are doing. If it is primarily SELECT statements, then you can use asynchronous mode and let the database engine run, since you are calling back in anyway for the row/results. If you are primarily doing database maintenance (that is, INSERT, UPDATE, and DELETE statements), then you probably want synchronous statement execution so you can just use one API call.

Returns:

A valid pointer to an opaque database connection (qdb_hdl_t), NULL if an error occurred (errno is set).

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

qdb_disconnect(), qdb_setbusytimeout(), qdb_statement()