Information to bind data to an SQL statement variable
#include <qdb/qdb.h> typedef struct { int index; int type; int len; const void *data; unsigned long long intcopy; } qdb_binding_t;
The qdb_binding_t structure stores the information needed to bind a data value to a variable parameter in a prepared SQL statement. This information includes fields describing the data type and length as well as a reference to the data value.
You should always initialize an instance of qdb_binding_t with one of the convenience macros. It is not recommended to manually set the fields in the binding structure one by one.
The variables in the macro prototypes have these meanings:
The following macros can be used to define a single data-binding structure:
The single-structure macros are useful only when your statement has one variable. In this case, you can just pass in the address of the structure when calling qdb_stmt_exec() (and set binding_count to 1 to indicate there's only one binding item). If you need to define multiple variables, you must declare an array of qdb_binding_t structures and then fill in the individual array entries. You can do this by using the array-based data-binding macros.
These macros have names of the form QDB_SETARRAYBIND_*. There is a matching array macro for each single-structure macro, with identical parameters. For example, QDB_SETARRAYBIND accepts the same five parameters as QDB_SETBIND, and binds any specified data type. The only difference is that for array macros, the i argument acts as an index not only for the variable parameter being bound but also for the array entry being written.
Suppose you're using an array of binding structures to assign data to multiple variable parameters in an SQL statement. To bind the first parameter, call one of the macro arrays with the index i set to 1 to fill in the first structure in the array. For the second parameter, use an index of 2, and so on.
After you've defined the data for the statement variables, you can execute the SQL statement by calling qdb_stmt_exec(), passing in the statement ID and a reference to the array of qdb_binding_t structures. Any variables that aren't defined are interpreted as NULL.
There's a limit to the amount of data that can be sent to a database with qdb_stmt_exec(). This limit is the lesser of the following values:
The following code sample shows the difference between the QDB_SETBIND_INT and QDB_SETBIND_INTCOPY macros:
qdb_binding_t qbind[2]; int64_t i = 17; QDB_SETARRAYBIND_INT(qbind, 1, i); QDB_SETARRAYBIND_INTCOPY(qbind, 2, i); int stmtid = qdb_stmt_init( "INSERT INTO testtable (val1, val2) VALUES (?1, ?2);"); for (i=0; i<10; i++) { qdb_stmt_exec(stmtid, qbind, 2); }
Both bound parameters refer to the local variable i initially. However, the loop uses this variable as the index, causing a different value to be inserted in the first column each time qdb_stmt_exec() runs. The first parameter changes because QDB_SETBIND_INT only stores the variable address (and not the value itself) in the binding structure, so modifying the variable modifies the bound value as well. The second parameter remains unchanged because QDB_SETBIND_INTCOPY makes a copy of the passed-in value. So, the resulting table values are:
val1 | val2 =========== 0 | 17 1 | 17 2 | 17 ... 9 | 17
See qdb_stmt_init() for an example on how to compile, execute, and free an SQL statement.