dbapi.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: dbapi.hpp,v $
 * PRODUCTION Revision 1000.3  2004/06/01 19:17:52  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.30
 * PRODUCTION
 * ===========================================================================
 */

#ifndef DBAPI___DBAPI__HPP
#define DBAPI___DBAPI__HPP

/* $Id: dbapi.hpp,v 1000.3 2004/06/01 19:17:52 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author:  Michael Kholodov
 *   
 * File Description:  Database API interface
 *
 */

#include <corelib/ncbiobj.hpp>
#include <dbapi/driver_mgr.hpp>
#include <dbapi/variant.hpp>


/** @addtogroup DbAPI
 *
 * @{
 */


BEGIN_NCBI_SCOPE


/////////////////////////////////////////////////////////////////////////////
//
//  EDataSource::
//
//  Data source platform
//
// enum EDataSource {
//   eSybase,
//   eMsSql
// };



/////////////////////////////////////////////////////////////////////////////
//
//  EAllowLog::
//
//  Allow transaction log (general, to avoid using bools)
//
enum EAllowLog {
   eDisableLog,
   eEnableLog
};  



/////////////////////////////////////////////////////////////////////////////
//
//  IResultSetMetaData::
//
//  Used for retrieving column information from a resultset, such as 
//  total number of columns, type, name, etc.
//

class NCBI_DBAPI_EXPORT IResultSetMetaData 
{
public:
    virtual ~IResultSetMetaData();

    virtual unsigned int GetTotalColumns() const = 0;
    virtual EDB_Type     GetType    (unsigned int col) const = 0;
    virtual int          GetMaxSize (unsigned int col) const = 0;
    virtual string       GetName    (unsigned int col) const = 0;
};



/////////////////////////////////////////////////////////////////////////////
//
//  IResultSet::
//
//  Used to retrieve a resultset from a query or cursor
//

class NCBI_DBAPI_EXPORT IResultSet
{
public:
    virtual ~IResultSet();

    // See in <dbapi/driver/interfaces.hpp> for the list of result types
    virtual EDB_ResType GetResultType() = 0;

    // Get next row.
    // NOTE:  no results are fetched before first call to this function.
    virtual bool Next() = 0;

    // All data (for BLOB data see below) is returned as CVariant.
    virtual const CVariant& GetVariant(unsigned int col) = 0;
    virtual const CVariant& GetVariant(const string& colName) = 0;

    // Disables column binding.
    // False by default
    virtual void DisableBind(bool b) = 0;

    // If this mode is true, BLOB data is returned as CVariant
    // False by default
    virtual void BindBlobToVariant(bool b) = 0;
  
    // Reads unformatted data, returns bytes actually read.
    // Advances to next column as soon as data is read from the previous one.
    // Returns 0 when the column data is fully read
    // Valid only when the column binding is off (see DisableBind())
    virtual size_t Read(void* buf, size_t size) = 0;

    // Return true if the last column read was NULL.
    // Valid only when the column binding is off (see DisableBind())
    virtual bool WasNull() = 0;

    // Returns current column number (while using Read())
    virtual int GetColumnNo() = 0;

    // Returns total number of columns in the resultset
    virtual unsigned int GetTotalColumns() = 0;
  
    // Streams for handling BLOBs.
    // NOTE: buf_size is the size of internal buffer, default 1024
    virtual istream& GetBlobIStream(size_t buf_size = 1024) = 0;
    // blob_size is the size of the BLOB to be written
    // log_it enables transaction log for BLOB insert by default.
    // Make sure you have enough log segment space, or disable it
    virtual ostream& GetBlobOStream(size_t blob_size, 
                                    EAllowLog log_it = eEnableLog,
                                    size_t buf_size = 1024) = 0;

    // Close resultset
    virtual void Close() = 0;

    // Get column description.
    virtual const IResultSetMetaData* GetMetaData() = 0;
};



/////////////////////////////////////////////////////////////////////////////
//
//  IStatement::
//
//  Interface for a SQL statement
//

class NCBI_DBAPI_EXPORT IStatement
{
public:
    virtual ~IStatement();
  
    // Get resulset. For statements with no resultset returns 0
    virtual IResultSet* GetResultSet() = 0;

    // Check if there is more results available
    virtual bool HasMoreResults() = 0;

    // Check if the statement failed
    virtual bool Failed() = 0;
  
    // Check if resultset is not empty
    virtual bool HasRows() = 0;

    // Purge results
    // NOTE: Calls fetch for every resultset received until
    // finished. 
    virtual void PurgeResults() = 0;

    // Cancel statement
    // NOTE: Rolls back current transaction
    virtual void Cancel() = 0;

    // Close statement
    virtual void Close() = 0;
  
    // Executes one or more SQL statements
    virtual void Execute(const string& sql) = 0;

    // Executes SQL statement with no results returned
    // NOTE: All resultsets are discarded.
    virtual void ExecuteUpdate(const string& sql) = 0;

    // Exectues SQL statement and returns the first resultset.
    // NOTE: If there is more than one resultset, the rest remain
    // pending unless either PurgeResults() is called or next statement
    // is run or the statement is closed.
    virtual IResultSet* ExecuteQuery(const string& sql) = 0;

    // Executes the last command (with changed parameters, if any)
    virtual void ExecuteLast() = 0;

    // Set input/output parameter
    virtual void SetParam(const CVariant& v, 
	  		  const string& name) = 0;

    // Clear parameter list
    virtual void ClearParamList() = 0;

    // Get total of rows returned. 
    // NOTE: Valid only after all rows are retrieved from a resultset
    virtual int GetRowCount() = 0;

    // Get the parent connection
    // NOTE: if the original connections was cloned, returns cloned
    // connection
    virtual class IConnection* GetParentConn() = 0;

};


/////////////////////////////////////////////////////////////////////////////
//
//  ICallableStatement::
//
//  Used for calling a stored procedure thru RPC call
//

class NCBI_DBAPI_EXPORT ICallableStatement : public virtual IStatement
{
public:
    virtual ~ICallableStatement();
  
    // Execute stored procedure
    virtual void Execute() = 0;

    // Executes stored procedure no results returned
    // NOTE: All resultsets are discarded.
    virtual void ExecuteUpdate() = 0;

    // Get return status from the stored procedure
    virtual int GetReturnStatus() = 0;

    // Set input parameters
    virtual void SetParam(const CVariant& v, 
                          const string& name) = 0;

    // Set output parameter, which will be returned as resultset
    // NOTE: use CVariant(EDB_Type type) constructor or 
    // factory method CVariant::<type>(0) to create empty object
    // of a particular type
    virtual void SetOutputParam(const CVariant& v, const string& name) = 0;

protected:
    // Mask unused methods
    virtual void Execute(const string& /*sql*/);
    virtual void ExecuteUpdate(const string& /*sql*/);
    virtual IResultSet* ExecuteQuery(const string& /*sql*/);

};


/////////////////////////////////////////////////////////////////////////////
//
//  ICursor::
//
//  Interface for a cursor
//

class NCBI_DBAPI_EXPORT ICursor
{
public:

    virtual ~ICursor();
  
    // Set input parameter
    virtual void SetParam(const CVariant& v, 
			const string& name) = 0;

    // Open cursor and get corresponding resultset
    virtual IResultSet* Open() = 0;

    // Get output stream for BLOB updates, requires BLOB column number
    // NOTE: blob_size is the size of the BLOB to be written
    // log_it enables transaction log for BLOB insert by default.
    // Make sure you have enough log segment space, or disable it
    virtual ostream& GetBlobOStream(unsigned int col,
                                    size_t blob_size, 
                                    EAllowLog log_it = eEnableLog,
                                    size_t buf_size = 1024) = 0;
    // Update statement for cursor
    virtual void Update(const string& table, const string& updateSql) = 0;