NAME

sqlbox_finalise —

finalise a statement

LIBRARY

library “sqlbox”

SYNOPSIS

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

int
sqlbox_finalise(struct sqlbox *box, size_t id);

DESCRIPTION

Finalise (close and free resources) the statement id as returned by sqlbox_prepare_bind(3). If id is zero, the last prepared statement is used. After being called, the statement may no longer be used.

SQLite3 Implementation

Invokes sqlite3_finalize(3).

RETURN VALUES

Return zero if id is invalid or communication with the box fails, non-zero otherwise.

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

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

EXAMPLES

The following example opens (or creates) database db.db, creates a table, and exits. The database is closed automatically by sqlbox_free(3).

size_t dbid, stmtid;
struct sqlbox *p;
struct sqlbox_cfg cfg;
struct sqlbox_src srcs[] = {
  { .fname = (char *)"db.db",
    .mode = SQLBOX_SRC_RWC }
};
struct sqlbox_pstmt pstmts[] = {
  { .stmt = (char *)"CREATE TABLE foo (bar INTEGER)" }
};
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 = pstmts;

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, 0, 0, NULL, 0)))
  errx(EXIT_FAILURE, "sqlbox_prepare_bind");
if ((res = sqlbox_step(p, stmtid)) == NULL)
  errx(EXIT_FAILURE, "sqlbox_step");
if (!sqlbox_finalise(p, stmtid))
  errx(EXIT_FAILURE, "sqlbox_finalise");

sqlbox_free(p);