include/qore/DBI.h (4311)

Go to the documentation of this file.

/* -*- mode: c++; indent-tabs-mode: nil -*- */
/*
  DBI.h

  Qore Programming Language

  Copyright 2003 - 2011 David Nichols

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

#ifndef _QORE_DBI_H
#define _QORE_DBI_H


// DBI Driver capabilities
#define DBI_CAP_NONE                     0
#define DBI_CAP_TIME_ZONE_SUPPORT        (1 << 0)
#define DBI_CAP_CHARSET_SUPPORT          (1 << 1)
#define DBI_CAP_TRANSACTION_MANAGEMENT   (1 << 2)
#define DBI_CAP_STORED_PROCEDURES        (1 << 3)
#define DBI_CAP_LOB_SUPPORT              (1 << 4)
#define DBI_CAP_BIND_BY_VALUE            (1 << 5)
#define DBI_CAP_BIND_BY_PLACEHOLDER      (1 << 6)
#define DBI_CAP_HAS_EXECRAW              (1 << 7)
#define DBI_CAP_HAS_STATEMENT            (1 << 8)
#define DBI_CAP_HAS_SELECT_ROW           (1 << 9)

#define BN_PLACEHOLDER  0
#define BN_VALUE        1

#define DBI_DEFAULT_STR_LEN 512

// DBI method codes
#define QDBI_METHOD_OPEN                      1
#define QDBI_METHOD_CLOSE                     2
#define QDBI_METHOD_SELECT                    3
#define QDBI_METHOD_SELECT_ROWS               4
#define QDBI_METHOD_EXEC                      5
#define QDBI_METHOD_COMMIT                    6
#define QDBI_METHOD_ROLLBACK                  7
#define QDBI_METHOD_BEGIN_TRANSACTION         8
#define QDBI_METHOD_ABORT_TRANSACTION_START   9
#define QDBI_METHOD_GET_SERVER_VERSION       10
#define QDBI_METHOD_GET_CLIENT_VERSION       11
#define QDBI_METHOD_EXECRAW                  12
#define QDBI_METHOD_STMT_PREPARE             13
#define QDBI_METHOD_STMT_PREPARE_RAW         14
#define QDBI_METHOD_STMT_BIND                15
#define QDBI_METHOD_STMT_BIND_PLACEHOLDERS   16
#define QDBI_METHOD_STMT_BIND_VALUES         17
#define QDBI_METHOD_STMT_EXEC                18
#define QDBI_METHOD_STMT_FETCH_ROW           19
#define QDBI_METHOD_STMT_FETCH_ROWS          20
#define QDBI_METHOD_STMT_FETCH_COLUMNS       21
#define QDBI_METHOD_STMT_NEXT                22
#define QDBI_METHOD_STMT_CLOSE               23
#define QDBI_METHOD_STMT_AFFECTED_ROWS       24
#define QDBI_METHOD_STMT_GET_OUTPUT          25
#define QDBI_METHOD_STMT_GET_OUTPUT_ROWS     26
#define QDBI_METHOD_STMT_DEFINE              27
#define QDBI_METHOD_SELECT_ROW               28

#define QDBI_VALID_CODES 28

class Datasource;
class ExceptionSink;
class QoreString;
class QoreListNode;
class AbstractQoreNode;
class QoreHashNode;
class QoreNamespace;
class SQLStatement;

// DBI method signatures - note that only get_client_version uses a "const Datasource" 
// the others do not so that automatic reconnects can be supported (which will normally
// require writing to the Datasource)


typedef int (*q_dbi_open_t)(Datasource *ds, ExceptionSink *xsink);


typedef int (*q_dbi_close_t)(Datasource *ds);


typedef AbstractQoreNode *(*q_dbi_select_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink);


typedef AbstractQoreNode *(*q_dbi_select_rows_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink);


typedef QoreHashNode *(*q_dbi_select_row_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink);


typedef AbstractQoreNode *(*q_dbi_exec_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink);


typedef AbstractQoreNode *(*q_dbi_execraw_t)(Datasource *ds, const QoreString *str, ExceptionSink *xsink);


typedef int (*q_dbi_commit_t)(Datasource *ds, ExceptionSink *xsink);


typedef int (*q_dbi_rollback_t)(Datasource *ds, ExceptionSink *xsink);


typedef int (*q_dbi_begin_transaction_t)(Datasource *ds, ExceptionSink *xsink);


typedef int (*q_dbi_abort_transaction_start_t)(Datasource *ds, ExceptionSink *xsink);


typedef AbstractQoreNode *(*q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink);


typedef AbstractQoreNode *(*q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink);

// FIXME: document

typedef int (*q_dbi_stmt_prepare_t)(SQLStatement *stmt, const QoreString &str, const QoreListNode *args, ExceptionSink *xsink);


typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink);


typedef int (*q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink);


typedef int (*q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink);


typedef int (*q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink);


typedef QoreHashNode *(*q_dbi_stmt_get_output_t)(SQLStatement *stmt, ExceptionSink *xsink);


typedef QoreHashNode *(*q_dbi_stmt_get_output_rows_t)(SQLStatement *stmt, ExceptionSink *xsink);

typedef int (*q_dbi_stmt_define_t)(SQLStatement *stmt, ExceptionSink *xsink);
typedef QoreHashNode *(*q_dbi_stmt_fetch_row_t)(SQLStatement *stmt, ExceptionSink *xsink);
typedef QoreHashNode *(*q_dbi_stmt_fetch_columns_t)(SQLStatement *stmt, int rows, ExceptionSink *xsink);
typedef QoreListNode *(*q_dbi_stmt_fetch_rows_t)(SQLStatement *stmt, int rows, ExceptionSink *xsink);
typedef bool (*q_dbi_stmt_next_t)(SQLStatement *stmt, ExceptionSink *xsink);
typedef int (*q_dbi_stmt_close_t)(SQLStatement *stmt, ExceptionSink *xsink);

typedef std::pair<int, void *> qore_dbi_method_t;

typedef safe_dslist<qore_dbi_method_t> dbi_method_list_t;


class qore_dbi_method_list {
private:
   struct qore_dbi_mlist_private *priv; // private implementation

   // not implemented
   DLLLOCAL qore_dbi_method_list(const qore_dbi_method_list&);
   DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);

public:
   DLLEXPORT qore_dbi_method_list();
   DLLEXPORT ~qore_dbi_method_list();

   // covers open, commit, rollback, and begin transaction
   DLLEXPORT void add(int code, q_dbi_open_t method);
   // for close
   DLLEXPORT void add(int code, q_dbi_close_t method);
   // covers select, select_rows, and exec
   DLLEXPORT void add(int code, q_dbi_select_t method);
   // covers select_row
   DLLEXPORT void add(int code, q_dbi_select_row_t method);
   // covers execRaw
   DLLEXPORT void add(int code, q_dbi_execraw_t method);
   // covers get_server_version
   DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
   // covers get_client_version
   DLLEXPORT void add(int code, q_dbi_get_client_version_t method);

   // covers prepare
   DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
   // covers prepare_raw
   DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
   // covers bind, bind_placeholders, bind_values
   DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
   // covers exec, close, affected_rows, and define
   DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
   // covers fetch_row, get_output, and get_output_rows
   DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
   // covers fetch_columns
   DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
   // covers fetch_rows
   DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
   // covers next
   DLLEXPORT void add(int code, q_dbi_stmt_next_t method);

   // internal interface
   DLLLOCAL dbi_method_list_t *getMethods() const;
};


class DBIDriver {
private:
   struct qore_dbi_private *priv;

   DLLLOCAL DBIDriver(const DBIDriver&);
   DLLLOCAL DBIDriver& operator=(const DBIDriver&);

public:

   DLLEXPORT const char *getName() const;

   DLLLOCAL DBIDriver(const char *name, const dbi_method_list_t &methods, int cps);
   DLLLOCAL ~DBIDriver();
   DLLLOCAL int init(Datasource *ds, ExceptionSink *xsink) const;
   DLLLOCAL int close(Datasource *ds) const;
   DLLLOCAL AbstractQoreNode *select(Datasource *ds, const QoreString *sql, const QoreListNode *args, ExceptionSink *xsink) const;
   DLLLOCAL AbstractQoreNode *selectRows(Datasource *ds, const QoreString *sql, const QoreListNode *args, ExceptionSink *xsink) const;
   DLLLOCAL QoreHashNode *selectRow(Datasource *ds, const QoreString *sql, const QoreListNode *args, ExceptionSink *xsink) const;
   DLLLOCAL AbstractQoreNode *execSQL(Datasource *ds, const QoreString *sql, const QoreListNode *args, ExceptionSink *xsink) const;
   DLLLOCAL AbstractQoreNode *execRawSQL(Datasource *ds, const QoreString *sql, ExceptionSink *xsink) const;
   DLLLOCAL int commit(Datasource *, ExceptionSink *xsink) const;
   DLLLOCAL int rollback(Datasource *, ExceptionSink *xsink) const;
   DLLLOCAL int autoCommit(Datasource *, ExceptionSink *xsink) const;
   DLLLOCAL int beginTransaction(Datasource *, ExceptionSink *xsink) const;
   DLLLOCAL int abortTransactionStart(Datasource *, ExceptionSink *xsink) const;
   DLLLOCAL AbstractQoreNode *getServerVersion(Datasource *, ExceptionSink *xsink) const;
   DLLLOCAL AbstractQoreNode *getClientVersion(const Datasource *, ExceptionSink *xsink) const;

   DLLLOCAL int stmt_prepare(SQLStatement *stmt, const QoreString &str, const QoreListNode *args, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_prepare_raw(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_bind(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_bind_placeholders(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_bind_values(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_exec(SQLStatement *stmt, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_affected_rows(SQLStatement *stmt, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_define(SQLStatement *stmt, ExceptionSink *xsink) const;
   DLLLOCAL QoreHashNode *stmt_get_output(SQLStatement *stmt, ExceptionSink *xsink) const;
   DLLLOCAL QoreHashNode *stmt_get_output_rows(SQLStatement *stmt, ExceptionSink *xsink) const;

   DLLLOCAL QoreHashNode *stmt_fetch_row(SQLStatement *stmt, ExceptionSink *xsink) const;
   DLLLOCAL QoreListNode *stmt_fetch_rows(SQLStatement *stmt, int rows, ExceptionSink *xsink) const;
   DLLLOCAL QoreHashNode *stmt_fetch_columns(SQLStatement *stmt, int rows, ExceptionSink *xsink) const;
   DLLLOCAL bool stmt_next(SQLStatement *stmt, ExceptionSink *xsink) const;
   DLLLOCAL int stmt_close(SQLStatement *stmt, ExceptionSink *xsink) const;

   DLLLOCAL bool hasStatementAPI() const;

   DLLLOCAL int getCaps() const;
   DLLLOCAL QoreListNode *getCapList() const;
};

struct qore_dbi_dlist_private;


class DBIDriverList {
private:
   struct qore_dbi_dlist_private *priv;

   DLLLOCAL DBIDriver *find_intern(const char *name) const;

public:

   DLLEXPORT class DBIDriver *registerDriver(const char *name, const struct qore_dbi_method_list &methods, int caps);


   DLLEXPORT DBIDriver *find(const char *name) const;


   DLLEXPORT DBIDriver *find(const char *name, ExceptionSink *xsink) const;

   DLLLOCAL DBIDriverList();
   DLLLOCAL ~DBIDriverList();
   DLLLOCAL QoreListNode *getDriverList() const;
};

DLLEXPORT extern DBIDriverList DBI;

DLLEXPORT QoreHashNode *parseDatasource(const char *ds, ExceptionSink *xsink);

DLLEXPORT void DBI_concat_numeric(QoreString *str, const AbstractQoreNode *v);


DLLEXPORT int DBI_concat_string(QoreString *str, const AbstractQoreNode *v, ExceptionSink *xsink);

DLLLOCAL void init_dbi_functions();
DLLLOCAL QoreNamespace *getSQLNamespace();

#endif  // _QORE_DBI_H