DBI.h

Go to the documentation of this file.

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

  Qore Programming Language

  Copyright (C) 2003 - 2014 David Nichols

  Permission is hereby granted, free of charge, to any person obtaining a
  copy of this software and associated documentation files (the "Software"),
  to deal in the Software without restriction, including without limitation
  the rights to use, copy, modify, merge, publish, distribute, sublicense,
  and/or sell copies of the Software, and to permit persons to whom the
  Software is furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  DEALINGS IN THE SOFTWARE.

  Note that the Qore library is released under a choice of three open-source
  licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
  information.
*/

#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 DBI_CAP_HAS_NUMBER_SUPPORT       (1 << 10) 
#define DBI_CAP_HAS_OPTION_SUPPORT       (1 << 11) 
#define DBI_CAP_SERVER_TIME_ZONE         (1 << 12) 
#define DBI_CAP_AUTORECONNECT            (1 << 13) 
#define DBI_CAP_EVENTS                   (1 << 14) 
#define DBI_CAP_HAS_DESCRIBE             (1 << 15) 

#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_METHOD_OPT_SET                  29
#define QDBI_METHOD_OPT_GET                  30
#define QDBI_METHOD_STMT_DESCRIBE            31
#define QDBI_METHOD_DESCRIBE                 32

#define QDBI_VALID_CODES 32

/* DBI EVENT Types
   all DBI events must have the following keys:
   - user: db username (if available)
   - db: db name (if available)
   - eventtype: integer event code
*/
// warning events have the following additional keys: warning, desc, [info]
#define QDBI_EVENT_WARNING      1

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 int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const AbstractQoreNode* val, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);


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

#define DBI_OPT_NUMBER_OPT "optimal-numbers"      
#define DBI_OPT_NUMBER_STRING "string-numbers"    
#define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"  
#define DBI_OPT_TIMEZONE "timezone"               


class qore_dbi_method_list {
   friend struct qore_dbi_mlist_private;

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

   // covers set option
   DLLEXPORT void add(int code, q_dbi_option_set_t method);
   // covers get option
   DLLEXPORT void add(int code, q_dbi_option_get_t method);

   // for registering valid options
   DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
};


class DBIDriver {
   friend struct qore_dbi_private;

private:
   struct qore_dbi_private* priv;

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

public:

   DLLEXPORT const char* getName() const;

   DLLEXPORT bool hasStatementAPI() const;


   DLLEXPORT QoreHashNode* getOptionHash() const;

   DLLLOCAL DBIDriver(struct qore_dbi_private* p);
   DLLLOCAL ~DBIDriver();
};

struct qore_dbi_dlist_private;


class DBIDriverList {
private:
   struct qore_dbi_dlist_private *priv;

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

public:

   DLLEXPORT DBIDriver* registerDriver(const char* name, const 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);

#endif  // _QORE_DBI_H