SQLBOX_FINALISE(3)

NAME
sqlbox_finalise - finalise a statement

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);

SEE ALSO
sqlbox_ping(3), sqlbox_prepare_bind(3)