NAME

sqlbox_rebind —

rebind parameters to a statement

LIBRARY

library “sqlbox”

SYNOPSIS

#include <stdint.h>
#include <sqlbox.h>

size_t
sqlbox_rebind(struct sqlbox *box, size_t id, size_t psz, const struct sqlbox_parm *ps);

DESCRIPTION

Rebinds parameters to a statement id as returned by sqlbox_prepare_bind(3). If id is zero, the last prepared statement is used. This resets the statement and removes any previously-bound parameters. The number of parameters psz must match the prepared statement parameters given in the SQL or be zero.

The ps array, if psz is non-zero, consists of typed values bound to those parameters. Types must correspond to typed values, for example, floats of type SQLBOX_PARM_FLOAT must be set in the fparm of struct sqlbox_parm.

The sz of struct sqlbox_parm is ignored for floats and integers, but must be provided for blobs and optionally for strings. For strings, a zero indicates it should be computed using strlen(3). Otherwise, it should be the full string length including the NUL terminator. If the string is shorter than the given length (i.e., contains an embedded NUL terminator), the database will still return the full given length of the original size (terminating NUL inclusive).

SQLite3 Implementation

The statement is first reset with sqlite3_reset(3), its existing bound parameters removed with sqlite3_clear_bindings(3), then new parameters bound with sqlite3_bind_blob(3) and family.

RETURN VALUES

Returns zero if id is invalid, strings are not NUL-terminated at their size (if non-zero), memory allocation fails, or communication with box fails. Otherwise it returns the >0 statement identifier.

If rebinding to the statement fails, subsequent box access will fail. Use sqlbox_ping(3) to check explicitly.

If sqlbox_rebind() fails, box is no longer accessible beyond sqlbox_ping(3) and sqlbox_free(3).

EXAMPLES

The following examples opens an existing database db.db and inserts two rows. Assume that the database has two integer columns.

size_t dbid, stmtid;
struct sqlbox *p;
struct sqlbox_cfg cfg;
struct sqlbox_src srcs[] = {
  { .fname = (char *)"db.db",
    .mode = SQLBOX_SRC_RW }
};
struct sqlbox_pstmt pstmts = {
  .stmt = (char *)"INSERT INTO foo "
	"(bar, baz) VALUES (?,?)"
};
struct sqlbox_parm parms1[] = {
  { .iparm = 10,
    .type = SQLBOX_PARM_INT },
  { .iparm = 20,
    .type = SQLBOX_PARM_INT },
};
struct sqlbox_parm parms2[] = {
  { .iparm = 30,
    .type = SQLBOX_PARM_INT },
};
const struct sqlbox_parmset *res;

memset(&cfg, 0, sizeof(struct sqlbox_cfg));
cfg.msg.func_short = warnx;
cfg.srcs.srcsz = 1;
cfg.srcs.srcs = srcs;
cfg.stmts.stmtsz = 1;
cfg.stmts.stmts = &pstmt;

if ((p = sqlbox_alloc(&cfg)) == NULL)
  errx(EXIT_FAILURE, "sqlbox_alloc");
if (!(dbid = sqlbox_open(p, 0)))
  errx(EXIT_FAILURE, "sqlbox_open");
if (!(stmtid = sqlbox_prepare_bind(p, dbid, 1, 2, parms1, 0)))
  errx(EXIT_FAILURE, "sqlbox_prepare_bind");
if (sqlbox_step(p, stmtid) == NULL)
  errx(EXIT_FAILURE, "sqlbox_step");
if (!sqlbox_rebind(p, stmtid, 1, parms2))
  errx(EXIT_FAILURE, "sqlbox_rebind");
if (sqlbox_step(p, stmtid) == NULL)
  errx(EXIT_FAILURE, "sqlbox_step");
if (!sqlbox_finalise(p, stmtid))
  errx(EXIT_FAILURE, "sqlbox_finalise");

sqlbox_free(p);