qdb_stmt_init()

Initialize a precompiled statement

Synopsis:

#include <qdb/qdb.h>

int qdb_stmt_init( qdb_hdl_t *hdl,
    const char *sql,
    uint32_t len)

Arguments:

hdl
A pointer to the database handle.
sql
An SQL statement. This statement may contain variable parameters of the form ?n, where n is a number between 1 and 999. These placeholders can be filled in with data on a subsequent call to qdb_stmt_exec(). Parameters that aren't filled in are interpreted as NULL. For more informatin, see Parameters in the description of expressions, in the appendix: SQL Expressions Reference.
len
The length of sql.

Library:

qdb

Description:

This function initializes a prepared (precompiled) SQL statement. A prepared statement is compiled once, and can be executed multiple times (with calls to qdb_stmt_exec()). This function returns a statement ID for the precompiled statement, which you need to pass in to qdb_stmt_exec().

QDB executes precompiled statements faster than uncompiled statements, so this approach can optimize your application's performance when executing frequently used statements.

You can free precompiled statements using qdb_stmt_free(), although all precompiled statements are freed when you call qdb_disconnect().

Returns:

>0
Success. The returned value is the prepared statement ID, which you pass to qdb_stmt_exec() and qdb_stmt_free().
-1
An error occurred (errno is set).

Examples:

The following code snippet shows how you could compile and execute a simple statement:

int           stmtid;
qdb_binding_t qbind[2];
uint64_t      msid, limit;

const char   *sql = "SELECT fid FROM library WHERE msid=?1 LIMIT ?2;";

stmtid = qdb_stmt_init(db, sql, strlen(sql)+1);

if (stmtid == -1) {
     // Could not compile
     return -1;
}

msid = 1;
limit = 10;
QDB_SETBIND_INT(&qbind[0], 1, msid);
QDB_SETBIND_INT(&qbind[1], 2, limit);

if (qdb_stmt_exec(db, stmtid, qbind, 2) == -1) {
     // Could not execute
     return -1;
}

qdb_stmt_free(db, stmtid);


Note: Note the +1 added to the length of the string returned by strlen(); this sends QDB the final NULL character required of a valid string.

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

qdb_stmt_exec(), qdb_stmt_free()