NCBI C++ ToolKit
dbapi.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef DBAPI___DBAPI__HPP
2 #define DBAPI___DBAPI__HPP
3 
4 /* $Id: dbapi.hpp 92224 2020-12-23 19:08:29Z grichenk $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Michael Kholodov
30  *
31  * File Description: Database API interface
32  *
33  */
34 
35 /// @file dbapi.hpp
36 /// Defines the database API innterfaces for a variety of DBMS.
37 
38 #include <corelib/ncbiobj.hpp>
40 #include <dbapi/driver_mgr.hpp>
41 #include <dbapi/variant.hpp>
42 
43 
44 /** @addtogroup DbAPI
45  *
46  * @{
47  */
48 
49 
51 
52 
53 /////////////////////////////////////////////////////////////////////////////
54 ///
55 /// EDataSource --
56 ///
57 /// Data source platform
58 ///
59 /// enum EDataSource {
60 /// eSybase,
61 /// eMsSql
62 /// };
63 
64 
65 
66 /////////////////////////////////////////////////////////////////////////////
67 ///
68 /// EAllowLog --
69 ///
70 /// Allow transaction log (general, to avoid using bools).
71 ///
72 enum EAllowLog {
73  eDisableLog, ///< Disables log.
74  eEnableLog ///< Enables log.
75 };
76 
77 
78 /////////////////////////////////////////////////////////////////////////////
79 ///
80 /// EBlobOStreamFlags --
81 ///
82 /// How to send BLOB data (generalization of EAllowLog).
83 ///
85  /// Use a (sub)transaction (committed once all data's been sent
86  /// successfully, rolled back for unrecoverable errors) to guard
87  /// against races that could let readers see incomplete blobs, and
88  /// to allow for replication as appropriate. NB: This approach can
89  /// yield local deadlocks in some circumstances, particularly if a
90  /// single application thread maintains multiple connections to the
91  /// database in question (due, for instance, to using methods that
92  /// establish temporary clones of the original connection).
94  fBOS_SkipLogging = 1 << 1 //< Don't request server-side logging.
95 };
96 
97 typedef int TBlobOStreamFlags; //< Binary OR of EBlobOStreamFlags
98 
99 
100 /////////////////////////////////////////////////////////////////////////////
101 ///
102 /// IResultSetMetaData --
103 ///
104 /// Interface class defines retrieving column information from a resultset,
105 /// such as total number of columns, type, name, etc.
106 
108 {
109 public:
110  /// Destructor.
111  ///
112  /// Clean up the metadata for the resultset.
113  virtual ~IResultSetMetaData(void);
114 
115  /// Convenience method to check whether a column with a given name
116  /// (or number) actually exists.
117  bool HasColumn(const CDBParamVariant& param) const;
118 
119  /// Get total number of columns in resultset.
120  virtual unsigned int GetTotalColumns(void) const = 0;
121 
122  /// Get data type for column in the resultset.
123  ///
124  /// @param param
125  /// Column number or name
126  virtual EDB_Type GetType(const CDBParamVariant& param) const = 0;
127 
128  /// Get maximum size in bytes for column.
129  ///
130  /// @param col
131  /// Column number
132  ///
133  /// @return
134  /// Max number of bytes needed to hold the returned data.
135  virtual int GetMaxSize (const CDBParamVariant& param) const = 0;
136 
137  /// Get name of column.
138  ///
139  /// @param param
140  /// Column number or name
141  virtual string GetName (const CDBParamVariant& param) const = 0;
142 
143  /// Get parameter's direction (in/out/inout).
144  ///
145  /// @param param
146  /// Column number or name
147  virtual CDBParams::EDirection GetDirection(const CDBParamVariant& param) const = 0;
148 };
149 
150 
151 
152 /////////////////////////////////////////////////////////////////////////////
153 ///
154 /// IResultSet --
155 ///
156 /// Used to retrieve a resultset from a query or cursor
157 
158 class IConnection;
159 
161 {
162 public:
163  /// Destructor.
164  ///
165  /// Clean up the resultset.
166  virtual ~IResultSet();
167 
168  /// Get result type.
169  ///
170  /// @sa
171  /// See in <dbapi/driver/interfaces.hpp> for the list of result types.
172  virtual EDB_ResType GetResultType() = 0;
173 
174  /// Get next row.
175  ///
176  /// NOTE: no results are fetched before first call to this function.
177  virtual bool Next() = 0;
178 
179  /// Retrieve a CVariant class describing the data stored in a given column.
180  /// Note that the index supplied is one-based, not zero-based; the first
181  /// column is column 1.
182  ///
183  /// @param param
184  /// Column number (one-based) or name
185  /// @return
186  /// All data (for BLOB data see below) is returned as CVariant.
187  virtual const CVariant& GetVariant(const CDBParamVariant& param) = 0;
188 
189  /// Disables column binding.
190  /// @note
191  /// When binding is disabled all columns must be read with Read()
192  /// method, GetVariant() method will always return NULL in this case.
193  ///
194  /// False by default.
195  /// @param
196  /// Disables column binding when set to true.
197  virtual void DisableBind(bool b) = 0;
198 
199  /// Bind blob to variant.
200  ///
201  /// If this mode is true, BLOB data is returned as CVariant
202  /// False by default.
203  /// @note
204  /// When binding of blobs to variant is disabled all columns in
205  /// resultset placed after first blob column must be read with Read()
206  /// method, GetVariant() method will always return NULL for these
207  /// columns.
208  ///
209  /// @param
210  /// Enables blob binding when set to true.
211  virtual void BindBlobToVariant(bool b) = 0;
212 
213  /// Read unformatted data.
214  ///
215  /// Reads unformatted data, returns bytes actually read.
216  /// Advances to next column as soon as data is read from the previous one.
217  /// Returns 0 when the column data is fully read
218  /// Valid only when the column binding is off (see DisableBind())
219  /// @param buf
220  /// Buffer to read data.
221  /// @param size
222  /// Amount of data to read.
223  /// @return
224  /// Actual number of bytes read.
225  virtual size_t Read(void* buf, size_t size) = 0;
226 
227  /// Determine if last column was NULL.
228  ///
229  /// Valid only when the column binding is off.
230  /// @return
231  /// Return true if the last column read was NULL.
232  /// @sa
233  /// DisableBind().
234  virtual bool WasNull() = 0;
235 
236  /// Get column number, currently available for Read()
237  ///
238  /// @return
239  /// Returns current item number we can retrieve (1,2,...) using Read()
240  /// Returns "0" if no more items left (or available) to read
241  virtual int GetColumnNo() = 0;
242 
243  /// Get total columns.
244  ///
245  /// @return
246  /// Returns total number of columns in the resultset
247  virtual unsigned int GetTotalColumns() = 0;
248 
249  /// Get Blob input stream.
250  ///
251  /// @param buf_size
252  /// buf_size is the size of internal buffer, default 4096.
253  virtual CNcbiIstream& GetBlobIStream(size_t buf_size = 0) = 0;
254 
255  /// Get Blob output stream. The existing connection is
256  /// cloned for writing blob.
257  ///
258  /// @param blob_size
259  /// blob_size is the size of the BLOB to be written.
260  /// @param flags
261  /// @see EBlobOStreamFlags.
262  /// @param buf_size
263  /// The size of internal buffer, default 4096.
264  /// @deprecated
265  /// Please use IStatement::GetBlobOStream instead.
266  /// @sa
267  /// IStatement::GetBlobOStream
269  virtual CNcbiOstream& GetBlobOStream(size_t blob_size,
271  size_t buf_size = 0) = 0;
272 
274  virtual CNcbiOstream& GetBlobOStream(size_t blob_size,
275  EAllowLog log_it,
276  size_t buf_size = 0);
277 
278  /// Get Blob output stream with explicit additional connection.
279  ///
280  /// @param conn
281  /// addtional connection used for writing blob (the above method
282  /// clones the existing connection implicitly)
283  /// @param blob_size
284  /// blob_size is the size of the BLOB to be written.
285  /// @param flags
286  /// @see EBlobOStreamFlags.
287  /// @param buf_size
288  /// The size of internal buffer, default 4096.
289  /// @deprecated
290  /// Please use IStatement::GetBlobOStream instead.
291  /// @sa
292  /// IStatement::GetBlobOStream
295  size_t blob_size,
297  size_t buf_size = 0) = 0;
298 
300  virtual CNcbiOstream& GetBlobOStream(IConnection *conn,
301  size_t blob_size,
302  EAllowLog log_it,
303  size_t buf_size = 0);
304 
305  /// Get a Blob Reader.
306  ///
307  /// @param
308  /// Pointer to the Blob Reader.
309  virtual IReader* GetBlobReader() = 0;
310 
311  /// Close resultset.
312  virtual void Close() = 0;
313 
314  /// Get Metadata.
315  ///
316  /// @return
317  /// Pointer to result metadata.
318  virtual const IResultSetMetaData* GetMetaData(EOwnership ownership = eNoOwnership) = 0;
319 };
320 
321 
322 
323 /////////////////////////////////////////////////////////////////////////////
324 ///
325 /// IStatement --
326 ///
327 /// Interface for a SQL statement
328 
329 class I_BlobDescriptor;
330 
332 {
333 public:
334  /// Destructor.
335  virtual ~IStatement();
336 
337  /// Get resulset.
338  ///
339  /// @return
340  /// Pointer to resultset. For statements with no resultset return 0.
341  virtual IResultSet* GetResultSet() = 0;
342 
343  /// Check for more results available.
344  ///
345  /// Each call advances to the next result and the current one
346  /// will be cancelled it not retrieved before next call.
347  /// The amount of retured results may be bigger than the expected amount
348  /// due to auxiliary results returned depending on the driver and server
349  /// platform.
350  ///
351  /// @return
352  /// Return true, if there are more results available.
353  virtual bool HasMoreResults() = 0;
354 
355  /// Check if the statement failed.
356  ///
357  /// @return
358  /// Return true, if the statement failed.
359  virtual bool Failed() = 0;
360 
361  /// Check if resultset has rows.
362  ///
363  /// @return
364  /// Return true, if resultset has rows.
365  virtual bool HasRows() = 0;
366 
367  /// Purge results.
368  ///
369  /// Calls fetch for every resultset received until
370  /// finished.
371  virtual void PurgeResults() = 0;
372 
373  /// Cancel statement.
374  ///
375  /// Rolls back current transaction.
376  virtual void Cancel() = 0;
377 
378  /// Close statement.
379  virtual void Close() = 0;
380 
381  /// Sends one or more SQL statements to the SQL server
382  ///
383  /// @param sql
384  /// SQL statement to execute.
385  virtual void SendSql(const string& sql) = 0;
386 
387  /// Sends one or more SQL statements to the SQL server (NOTE: replaced by
388  /// the SendSql())
389  ///
390  /// @param sql
391  /// SQL statement to execute.
392  /// @deprecated
393  /// Use SendSql() instead
394  virtual void Execute(const string& sql) = 0;
395 
396  /// Executes SQL statement with no results returned.
397  ///
398  /// All resultsets are discarded.
399  /// @param sql
400  /// SQL statement to execute.
401  virtual void ExecuteUpdate(const string& sql) = 0;
402 
403  /// Exectues SQL statement and returns the first resultset.
404  ///
405  /// If there is more than one resultset, the rest remain
406  /// pending unless either PurgeResults() is called or next statement
407  /// is run or the statement is closed.
408  /// NOTE: Provided only for queries containing a single sql statement returning rows.
409  /// @param sql
410  /// SQL statement to execute.
411  /// @return
412  /// Pointer to result set. Ownership of IResultSet* belongs to IStatement.
413  /// It is not allowed to use unique_ptr<> or other smart pointers to manage
414  /// life-time of IResultSet*.
415  virtual IResultSet* ExecuteQuery(const string& sql) = 0;
416 
417  /// Executes the last command (with changed parameters, if any).
418  virtual void ExecuteLast() = 0;
419 
420  /// Set input/output parameter.
421  ///
422  /// @param v
423  /// Parameter value.
424  /// @param name
425  /// Parameter name.
426  virtual void SetParam(const CVariant& v,
427  const CDBParamVariant& param) = 0;
428 
429  /// Clear parameter list.
430  virtual void ClearParamList() = 0;
431 
432  /// Get total of rows returned.
433  ///
434  /// Valid only after all rows are retrieved from a resultset.
435  /// Even then, can be -1 if the server didn't indicate a count.
436  virtual int GetRowCount() = 0;
437 
438  /// Get a writer for writing BLOBs using previously created
439  /// CDB_BlobDescriptor
440  /// @param d
441  /// Descriptor
442  /// @param blob_size
443  /// Size of BLOB to write
444  /// @param flags
445  /// @see EBlobOStreamFlags.
447  size_t blob_size,
448  TBlobOStreamFlags flags = 0) = 0;
449 
450  virtual IWriter* GetBlobWriter(I_BlobDescriptor &d,
451  size_t blob_size,
452  EAllowLog log_it);
453 
454  /// Get an ostream for writing BLOBs using previously created
455  /// CDB_BlobDescriptor
456  /// @param d
457  /// Descriptor
458  /// @param blob_size
459  /// Size of BLOB to write
460  /// @param flags
461  /// @see EBlobOStreamFlags.
462  /// @param buf_size
463  /// Buffer size, default 4096
465  size_t blob_size,
467  size_t buf_size = 0) = 0;
468 
469  virtual CNcbiOstream& GetBlobOStream(I_BlobDescriptor &d,
470  size_t blob_size,
471  EAllowLog log_it,
472  size_t buf_size = 0);
473 
474  /// Get the parent connection.
475  ///
476  /// If the original connections was cloned, returns cloned
477  /// connection.
478  virtual class IConnection* GetParentConn() = 0;
479 
480  /// Set auto-clear input parameter flag
481  ///
482  /// @param flag
483  /// auto-clear input parameter flag
484  /// In case when flag == true implicitly clear a statement's parameter list
485  /// after each Execute, ExecuteUpdate and ExecuteQuery call. Default value
486  //. is true.
487  virtual void SetAutoClearInParams(bool flag = true) = 0;
488 
489  /// Get auto-clear input parameter flag value
490  ///
491  /// @return
492  /// auto-clear input parameter flag value
493  virtual bool IsAutoClearInParams(void) const = 0;
494 
495  /// Get input parameters metadata.
496  ///
497  /// @return
498  /// Pointer to result metadata.
499  virtual const IResultSetMetaData& GetParamsMetaData(void) = 0;
500 };
501 
502 
503 /////////////////////////////////////////////////////////////////////////////
504 ///
505 /// ICallableStatement --
506 ///
507 /// Used for calling a stored procedure thru RPC call
508 
510 {
511 public:
512  /// Destructor.
513  virtual ~ICallableStatement();
514 
515  /// Execute stored procedure.
516  virtual void Execute() = 0;
517 
518  /// Executes stored procedure no results returned.
519  ///
520  /// NOTE: All resultsets are discarded.
521  virtual void ExecuteUpdate() = 0;
522 
523  /// Get return status from the stored procedure.
524  virtual int GetReturnStatus() = 0;
525 
526  /// Set input parameters.
527  ///
528  /// @param v
529  /// Parameter value.
530  /// @param name
531  /// Parameter name.
532  virtual void SetParam(const CVariant& v,
533  const CDBParamVariant& param) = 0;
534 
535  /// Set output parameter, which will be returned as resultset.
536  ///
537  /// NOTE: Use CVariant(EDB_Type type) constructor or
538  /// factory method CVariant::<type>(0) to create empty object
539  /// of a particular type.
540  /// @param v
541  /// Parameter value.
542  /// @param name
543  /// Parameter name.
544  virtual void SetOutputParam(const CVariant& v,
545  const CDBParamVariant& param) = 0;
546 
547 protected:
548  // Mask unused methods
549  virtual void SendSql(const string& /*sql*/);
550  virtual void Execute(const string& /*sql*/);
551  virtual void ExecuteUpdate(const string& /*sql*/);
552  virtual IResultSet* ExecuteQuery(const string& /*sql*/);
553 
554 };
555 
556 
557 /////////////////////////////////////////////////////////////////////////////
558 ///
559 /// ICursor --
560 ///
561 /// Interface for a cursor.
562 
564 {
565 public:
566  /// Destructor.
567  virtual ~ICursor();
568 
569  /// Set input parameter.
570  ///
571  /// @param v
572  /// Parameter value.
573  /// @param name
574  /// Parameter name.
575  virtual void SetParam(const CVariant& v,
576  const CDBParamVariant& param) = 0;
577 
578  /// Open cursor and get corresponding resultset.
579  virtual IResultSet* Open() = 0;
580 
581  /// Get output stream for BLOB updates, requires BLOB column number.
582  ///
583  /// @param col
584  /// Column number.
585  /// @param blob_size
586  /// blob_size is the size of the BLOB to be written.
587  /// @param flags
588  /// @see EBlobOStreamFlags.
589  /// @param buf_size
590  /// The size of internal buffer, default 4096.
591  /// @deprecated
592  /// Please use IStatement::GetBlobOStream instead.
593  /// @sa
594  /// IStatement::GetBlobOStream
596  virtual CNcbiOstream& GetBlobOStream(unsigned int col,
597  size_t blob_size,
599  size_t buf_size = 0) = 0;
600 
602  virtual CNcbiOstream& GetBlobOStream(unsigned int col,
603  size_t blob_size,
604  EAllowLog log_it,
605  size_t buf_size = 0);
606 
607  /// Get Blob Writer
608  ///
609  /// Implementation of IWriter interface
610  /// @param col
611  /// Column number.
612  /// @param blob_size
613  /// blob_size is the size of the BLOB to be written.
614  /// @param flags
615  /// @see EBlobOStreamFlags.
616  /// @deprecated
617  /// Please use IStatement::GetBlobWriter instead.
618  /// @sa
619  /// IStatement::GetBlobWriter
621  virtual IWriter* GetBlobWriter(unsigned int col,
622  size_t blob_size,
623  TBlobOStreamFlags flags = 0) = 0;
624 
626  virtual IWriter* GetBlobWriter(unsigned int col,
627  size_t blob_size,
628  EAllowLog log_it);
629 
630  /// Update statement for cursor.
631  ///
632  /// @param table
633  /// table name.
634  /// @param updateSql
635  /// SQL statement.
636  virtual void Update(const string& table, const string& updateSql) = 0;
637 
638  /// Delete statement for cursor.
639  ///
640  /// @param table
641  /// table name.
642  virtual void Delete(const string& table) = 0;
643 
644  /// Cancel cursor
645  virtual void Cancel() = 0;
646 
647  /// Close cursor
648  virtual void Close() = 0;
649 
650  /// Get the parent connection
651  ///
652  /// NOTE: If the original connections was cloned, returns cloned
653  /// connection.
654  virtual class IConnection* GetParentConn() = 0;
655 };
656 
657 
658 /////////////////////////////////////////////////////////////////////////////
659 ///
660 /// IBulkInsert --
661 ///
662 /// Interface for bulk insert
663 
665 {
666 public:
667  /// Destructor.
668  virtual ~IBulkInsert();
669 
670  /// Set hints by one call. Resets everything that was set by Add*Hint().
671  virtual void SetHints(CTempString hints) = 0;
672 
673  /// Type of hint that can be set.
674  enum EHints {
680  eFireTriggers
681  };
682 
683  /// Add hint with value.
684  /// Can be used with any hint type except eOrder and with e..PerBatch
685  /// value should be non-zero.
686  /// Resets everything that was set by SetHints().
687  virtual void AddHint(EHints hint, unsigned int value = 0) = 0;
688 
689  /// Add "ORDER" hint.
690  /// Resets everything that was set by SetHints().
691  virtual void AddOrderHint(CTempString columns) = 0;
692 
693  /// Bind column.
694  ///
695  /// @param col
696  /// Column number.
697  /// @param v
698  /// Variant value.
699  virtual void Bind(const CDBParamVariant& param, CVariant* v) = 0;
700 
701  /// Add row to the batch
702  virtual void AddRow() = 0;
703 
704  /// Store batch of rows
705  virtual void StoreBatch() = 0;
706 
707  /// Cancel bulk insert
708  virtual void Cancel() = 0;
709 
710  /// Complete batch
711  virtual void Complete() = 0;
712 
713  /// Close
714  virtual void Close() = 0;
715 };
716 
717 
718 
719 /////////////////////////////////////////////////////////////////////////////
720 ///
721 /// IConnection::
722 ///
723 /// Interface for a database connection.
724 
725 class IConnValidator;
726 
728 {
729 public:
730  /// Which connection mode.
731  enum EConnMode {
732  /// Bulk insert mode.
733  /// This value is not needed anymore because BCP mode is enabled
734  /// all the time in all drivers now.
735  eBulkInsert = I_DriverContext::fBcpIn,
736  /// Encrypted password mode.
737  ePasswordEncrypted = I_DriverContext::fPasswordEncrypted
738  };
739 
740  /// Destructor.
741  virtual ~IConnection();
742 
743  // Connection modes
744 
745  /// Set connection mode.
746  ///
747  /// @param mode
748  /// Mode to set to.
749  virtual void SetMode(EConnMode mode) = 0;
750 
751  /// Reset connection mode.
752  ///
753  /// @param mode
754  /// Mode to reset to.
755  virtual void ResetMode(EConnMode mode) = 0;
756 
757  /// Get mode mask.
758  virtual unsigned int GetModeMask() = 0;
759 
760  /// Force single connection mode, default false
761  ///
762  /// Disable this mode before using BLOB output streams
763  /// from IResultSet, because extra connection is needed
764  /// in this case.
765  virtual void ForceSingle(bool enable) = 0;
766 
767  /// Get parent datasource object.
768  virtual IDataSource* GetDataSource() = 0;
769 
770  /// Connect to a database.
771  ///
772  /// @param user
773  /// User name.
774  /// @param password
775  /// User's password.
776  /// @param server
777  /// Server to connect to.
778  /// @param database
779  /// Database to connect to.
780  virtual void Connect(const string& user,
781  const string& password,
782  const string& server,
783  const string& database = kEmptyStr) = 0;
784 
785  /// Connect to a database.
786  ///
787  /// @param params
788  /// Connection parameters. Parameters should include all necessary
789  /// settings because all info set via SetMode() or ResetMode() will
790  /// be ignored.
791  virtual void Connect(const CDBConnParams& params) = 0;
792 
793  /// Connect to a database using connect validator
794  ///
795  /// @param validator
796  /// Validator implementation class.
797  /// @param user
798  /// User name.
799  /// @param password
800  /// User's password.
801  /// @param server
802  /// Server to connect to.
803  /// @param database
804  /// Database to connect to.
805  virtual void ConnectValidated(IConnValidator& validator,
806  const string& user,
807  const string& password,
808  const string& server,
809  const string& database = kEmptyStr) = 0;
810 
811  /// Clone existing connection. All settings are copied except
812  /// message handlers
813  /// Set ownership to eTakeOwnership to prevent deleting
814  /// connection upon deleting parent object
816 
817  /// Set current database.
818  ///
819  /// @param name
820  /// Name of database to set to.
821  virtual void SetDatabase(const string& name) = 0;
822 
823  /// Get current database
824  virtual string GetDatabase() = 0;
825 
826  /// Check if the connection is alive
827  virtual bool IsAlive() = 0;
828 
829  // NEW INTERFACE: no additional connections created
830  // while using the next four methods.
831  // Objects obtained with these methods can't be used
832  // simultaneously (like opening cursor while a stored
833  // procedure is running on the same connection).
834 
835  /// Get statement object for regular SQL queries.
836  virtual IStatement* GetStatement() = 0;
837 
838  /// Get callable statement object for stored procedures.
839  ///
840  /// @param proc
841  /// Stored procedure name.
842  /// @param nofArgs
843  /// Number of arguments.
844  virtual ICallableStatement* GetCallableStatement(const string& proc) = 0;
847  {
848  return GetCallableStatement(proc);
849  }
850 
851  /// Get cursor object.
852  virtual ICursor* GetCursor(const string& name,
853  const string& sql,
854  int batchSize) = 0;
855  ICursor* GetCursor(const string& name,
856  const string& sql)
857  {
858  return GetCursor(name, sql, 1);
859  }
861  ICursor* GetCursor(const string& name,
862  const string& sql,
863  int,
864  int batchSize)
865  {
866  return GetCursor(name, sql, batchSize);
867  }
868 
869  /// Create bulk insert object.
870  ///
871  /// @param table_name
872  /// table name.
873  /// @param nof_cols
874  /// Number of columns.
875  virtual IBulkInsert* GetBulkInsert(const string& table_name) = 0;
877  IBulkInsert* GetBulkInsert(const string& table_name, unsigned int)
878  {
879  return GetBulkInsert(table_name);
880  }
881 
882  // END OF NEW INTERFACE
883 
884  /// Get statement object for regular SQL queries.
885  virtual IStatement* CreateStatement() = 0;
886 
887  /// Get callable statement object for stored procedures.
888  virtual ICallableStatement* PrepareCall(const string& proc) = 0;
890  ICallableStatement* PrepareCall(const string& proc, int)
891  {
892  return PrepareCall(proc);
893  }
894 
895  /// Get cursor object.
896  virtual ICursor* CreateCursor(const string& name,
897  const string& sql,
898  int batchSize) = 0;
899  ICursor* CreateCursor(const string& name,
900  const string& sql)
901  {
902  return CreateCursor(name, sql, 1);
903  }
905  ICursor* CreateCursor(const string& name,
906  const string& sql,
907  int,
908  int batchSize)
909  {
910  return CreateCursor(name, sql, batchSize);
911  }
912 
913  /// Create bulk insert object.
914  virtual IBulkInsert* CreateBulkInsert(const string& table_name) = 0;
916  IBulkInsert* CreateBulkInsert(const string& table_name, unsigned int)
917  {
918  return CreateBulkInsert(table_name);
919  }
920 
921  /// Close connecti
922  virtual void Close() = 0;
923 
924  /// Abort connection.
925  virtual void Abort() = 0;
926 
927  /// Set connection timeout.
928  /// NOTE: if "nof_secs" is zero or is "too big" (depends on the underlying
929  /// DB API), then set the timeout to infinite.
930  virtual void SetTimeout(size_t nof_secs) = 0;
931 
932  /// Set timeout for command cancellation and connection closing
933  virtual void SetCancelTimeout(size_t /*nof_secs*/) {}
934 
935  /// Get connection timeout.
936  virtual size_t GetTimeout(void) const;
937 
938  /// Get timeout for command cancellation and connection closing
939  virtual size_t GetCancelTimeout(void) const;
940 
941  /// If enabled, redirects all error messages
942  /// to CDB_MultiEx object (see below).
943  virtual void MsgToEx(bool v) = 0;
944 
945  /// Returns all error messages as a CDB_MultiEx object.
946  virtual CDB_MultiEx* GetErrorAsEx() = 0;
947 
948  /// Returns all error messages as a single string
949  virtual string GetErrorInfo() = 0;
950 
951  /// Returns the internal driver connection object
953 };
954 
955 
956 /////////////////////////////////////////////////////////////////////////////
957 ///
958 /// IDataSource --
959 ///
960 /// Interface for a datasource
961 
963 {
964  friend class CDriverManager;
965 
966 protected:
967  /// Protected Destructor.
968  ///
969  /// Prohibits explicit deletion.
970  /// Use CDriverManager::DestroyDs() call, instead.
971  virtual ~IDataSource();
972 
973 public:
974  // Get connection
975  // Set ownership to eTakeOwnership to prevent deleting
976  // connection upon deleting parent object
978 
979  /// Set login timeout.
980  virtual void SetLoginTimeout(unsigned int i) = 0;
981 
982  /// Set the output stream for server messages.
983  ///
984  /// Set it to zero to disable any output and collect
985  /// messages in CDB_MultiEx (see below).
986  /// @param out
987  /// Output stream to set to.
988  virtual void SetLogStream(ostream* out) = 0;
989 
990  /// Returns all server messages as a CDB_MultiEx object.
991  virtual CDB_MultiEx* GetErrorAsEx() = 0;
992 
993  /// Returns all server messages as a single string.
994  virtual string GetErrorInfo() = 0;
995 
996  /// Returns the pointer to the general driver interface.
998  virtual const I_DriverContext* GetDriverContext() const = 0;
999 
1000  // app_name defines the application name that a connection will use when
1001  // connecting to a server.
1002  void SetApplicationName(const string& app_name);
1003  string GetApplicationName(void) const;
1004 };
1005 
1006 
1007 ////////////////////////////////////////////////////////////////////////////////
1008 inline
1010 {
1011  return DBAPI_MakeTrans(*connection.GetCDB_Connection());
1012 }
1013 
1014 
1016 
1017 
1018 /* @} */
1019 
1020 #endif /* DBAPI___DBAPI__HPP */
Helper class to allow safe initialization from higher-layer objects.
Definition: public.hpp:1056
CDBConnParams::
Definition: interfaces.hpp:258
CTempString implements a light-weight string on top of a storage buffer whose lifetime management is ...
Definition: tempstr.hpp:65
CVariant –.
Definition: variant.hpp:99
IBulkInsert –.
Definition: dbapi.hpp:665
ICallableStatement –.
Definition: dbapi.hpp:510
ICursor –.
Definition: dbapi.hpp:564
IDataSource –.
Definition: dbapi.hpp:963
A very basic data-read interface.
IResultSetMetaData –.
Definition: dbapi.hpp:108
A very basic data-write interface.
I_BlobDescriptor::
Definition: interfaces.hpp:369
Abstract reader-writer interface classes.
static uch flags
std::ofstream out("events_result.xml")
main entry point for tests
static CS_CONNECTION * conn
Definition: ct_dynamic.c:25
static const char table_name[]
Definition: bcp.c:249
static char sql[1024]
Definition: putdata.c:19
static const char * proc
Definition: stats.c:21
static const column_t columns[]
Definition: utf8_2.c:22
@ eNoOwnership
No ownership is assumed.
Definition: ncbi_types.h:135
virtual IWriter * GetBlobWriter(unsigned int col, size_t blob_size, TBlobOStreamFlags flags=0)=0
Get Blob Writer.
virtual bool Next()=0
Get next row.
EConnMode
Which connection mode.
Definition: dbapi.hpp:731
virtual const I_DriverContext * GetDriverContext() const =0
virtual string GetName(const CDBParamVariant &param) const =0
Get name of column.
virtual size_t Read(void *buf, size_t size)=0
Read unformatted data.
ICursor * GetCursor(const string &name, const string &sql)
Definition: dbapi.hpp:855
virtual void Complete()=0
Complete batch.
virtual IResultSet * GetResultSet()=0
Get resulset.
virtual bool Failed()=0
Check if the statement failed.
IBulkInsert * GetBulkInsert(const string &table_name, unsigned int)
Definition: dbapi.hpp:877
virtual void SetTimeout(size_t nof_secs)=0
Set connection timeout.
IBulkInsert * CreateBulkInsert(const string &table_name, unsigned int)
Definition: dbapi.hpp:916
virtual void DisableBind(bool b)=0
Disables column binding.
virtual void SetParam(const CVariant &v, const CDBParamVariant &param)=0
Set input/output parameter.
virtual CNcbiOstream & GetBlobOStream(unsigned int col, size_t blob_size, TBlobOStreamFlags flags=0, size_t buf_size=0)=0
Get output stream for BLOB updates, requires BLOB column number.
virtual void Close()=0
Close resultset.
virtual bool HasMoreResults()=0
Check for more results available.
virtual IDataSource * GetDataSource()=0
Get parent datasource object.
virtual void Execute()=0
Execute stored procedure.
virtual void Close()=0
Close connecti.
virtual IResultSet * ExecuteQuery(const string &sql)=0
Exectues SQL statement and returns the first resultset.
virtual void Execute(const string &sql)=0
Sends one or more SQL statements to the SQL server (NOTE: replaced by the SendSql())
virtual IStatement * CreateStatement()=0
Get statement object for regular SQL queries.
ICursor * CreateCursor(const string &name, const string &sql, int, int batchSize)
Definition: dbapi.hpp:905
virtual const IResultSetMetaData * GetMetaData(EOwnership ownership=eNoOwnership)=0
Get Metadata.
virtual void Close()=0
Close.
virtual void SetOutputParam(const CVariant &v, const CDBParamVariant &param)=0
Set output parameter, which will be returned as resultset.
virtual void ConnectValidated(IConnValidator &validator, const string &user, const string &password, const string &server, const string &database=kEmptyStr)=0
Connect to a database using connect validator.
virtual const IResultSetMetaData & GetParamsMetaData(void)=0
Get input parameters metadata.
virtual void MsgToEx(bool v)=0
If enabled, redirects all error messages to CDB_MultiEx object (see below).
virtual CDB_Connection * GetCDB_Connection()=0
Returns the internal driver connection object.
virtual IBulkInsert * CreateBulkInsert(const string &table_name)=0
Create bulk insert object.
virtual void AddOrderHint(CTempString columns)=0
Add "ORDER" hint.
virtual void StoreBatch()=0
Store batch of rows.
virtual EDB_ResType GetResultType()=0
Get result type.
virtual CNcbiIstream & GetBlobIStream(size_t buf_size=0)=0
Get Blob input stream.
virtual void SetMode(EConnMode mode)=0
Set connection mode.
virtual ICallableStatement * PrepareCall(const string &proc)=0
Get callable statement object for stored procedures.
virtual string GetErrorInfo()=0
Returns all error messages as a single string.
virtual void Update(const string &table, const string &updateSql)=0
Update statement for cursor.
virtual void ResetMode(EConnMode mode)=0
Reset connection mode.
virtual int GetRowCount()=0
Get total of rows returned.
virtual CNcbiOstream & GetBlobOStream(I_BlobDescriptor &d, size_t blob_size, TBlobOStreamFlags flags=0, size_t buf_size=0)=0
Get an ostream for writing BLOBs using previously created CDB_BlobDescriptor.
virtual EDB_Type GetType(const CDBParamVariant &param) const =0
Get data type for column in the resultset.
virtual bool IsAlive()=0
Check if the connection is alive.
virtual void Abort()=0
Abort connection.
virtual IReader * GetBlobReader()=0
Get a Blob Reader.
virtual IConnection * CloneConnection(EOwnership ownership=eNoOwnership)=0
Clone existing connection.
virtual void SetLoginTimeout(unsigned int i)=0
Set login timeout.
ICallableStatement * GetCallableStatement(const string &proc, int)
Definition: dbapi.hpp:846
virtual CDB_MultiEx * GetErrorAsEx()=0
Returns all server messages as a CDB_MultiEx object.
virtual unsigned int GetTotalColumns(void) const =0
Get total number of columns in resultset.
virtual void Bind(const CDBParamVariant &param, CVariant *v)=0
Bind column.
EHints
Type of hint that can be set.
Definition: dbapi.hpp:674
virtual IStatement * GetStatement()=0
Get statement object for regular SQL queries.
virtual void PurgeResults()=0
Purge results.
virtual void ClearParamList()=0
Clear parameter list.
virtual string GetErrorInfo()=0
Returns all server messages as a single string.
virtual ICursor * GetCursor(const string &name, const string &sql, int batchSize)=0
Get cursor object.
virtual void ForceSingle(bool enable)=0
Force single connection mode, default false.
virtual unsigned int GetTotalColumns()=0
Get total columns.
virtual void BindBlobToVariant(bool b)=0
Bind blob to variant.
ICallableStatement * PrepareCall(const string &proc, int)
Definition: dbapi.hpp:890
virtual const CVariant & GetVariant(const CDBParamVariant &param)=0
Retrieve a CVariant class describing the data stored in a given column.
virtual string GetDatabase()=0
Get current database.
virtual I_DriverContext * GetDriverContext()=0
Returns the pointer to the general driver interface.
ICursor * CreateCursor(const string &name, const string &sql)
Definition: dbapi.hpp:899
virtual ICallableStatement * GetCallableStatement(const string &proc)=0
Get callable statement object for stored procedures.
virtual ICursor * CreateCursor(const string &name, const string &sql, int batchSize)=0
Get cursor object.
virtual int GetMaxSize(const CDBParamVariant &param) const =0
Get maximum size in bytes for column.
virtual void ExecuteUpdate()=0
Executes stored procedure no results returned.
virtual void ExecuteLast()=0
Executes the last command (with changed parameters, if any).
virtual void SetParam(const CVariant &v, const CDBParamVariant &param)=0
Set input parameters.
virtual void SetHints(CTempString hints)=0
Set hints by one call. Resets everything that was set by Add*Hint().
virtual CDB_MultiEx * GetErrorAsEx()=0
Returns all error messages as a CDB_MultiEx object.
virtual void AddHint(EHints hint, unsigned int value=0)=0
Add hint with value.
virtual bool WasNull()=0
Determine if last column was NULL.
virtual void Cancel()=0
Cancel cursor.
ICursor * GetCursor(const string &name, const string &sql, int, int batchSize)
Definition: dbapi.hpp:861
virtual void SetAutoClearInParams(bool flag=true)=0
Set auto-clear input parameter flag.
virtual void Close()=0
Close statement.
virtual class IConnection * GetParentConn()=0
Get the parent connection.
virtual IResultSet * Open()=0
Open cursor and get corresponding resultset.
virtual void Connect(const string &user, const string &password, const string &server, const string &database=kEmptyStr)=0
Connect to a database.
virtual IBulkInsert * GetBulkInsert(const string &table_name)=0
Create bulk insert object.
virtual void Connect(const CDBConnParams &params)=0
Connect to a database.
virtual class IConnection * GetParentConn()=0
Get the parent connection.
virtual void SetDatabase(const string &name)=0
Set current database.
int TBlobOStreamFlags
Definition: dbapi.hpp:97
virtual IWriter * GetBlobWriter(I_BlobDescriptor &d, size_t blob_size, TBlobOStreamFlags flags=0)=0
Get a writer for writing BLOBs using previously created CDB_BlobDescriptor.
virtual int GetReturnStatus()=0
Get return status from the stored procedure.
virtual void Close()=0
Close cursor.
virtual bool HasRows()=0
Check if resultset has rows.
virtual void Delete(const string &table)=0
Delete statement for cursor.
virtual bool IsAutoClearInParams(void) const =0
Get auto-clear input parameter flag value.
virtual void Cancel()=0
Cancel statement.
virtual void AddRow()=0
Add row to the batch.
virtual unsigned int GetModeMask()=0
Get mode mask.
virtual void Cancel()=0
Cancel bulk insert.
virtual void SetParam(const CVariant &v, const CDBParamVariant &param)=0
Set input parameter.
virtual int GetColumnNo()=0
Get column number, currently available for Read()
virtual void SetCancelTimeout(size_t)
Set timeout for command cancellation and connection closing.
Definition: dbapi.hpp:933
EAllowLog
EDataSource –.
Definition: dbapi.hpp:72
virtual CNcbiOstream & GetBlobOStream(IConnection *conn, size_t blob_size, TBlobOStreamFlags flags=0, size_t buf_size=0)=0
Get Blob output stream with explicit additional connection.
virtual CDBParams::EDirection GetDirection(const CDBParamVariant &param) const =0
Get parameter's direction (in/out/inout).
virtual void SetLogStream(ostream *out)=0
Set the output stream for server messages.
CAutoTrans::CSubject DBAPI_MakeTrans(IConnection &connection)
Definition: dbapi.hpp:1009
virtual void ExecuteUpdate(const string &sql)=0
Executes SQL statement with no results returned.
virtual IConnection * CreateConnection(EOwnership ownership=eNoOwnership)=0
virtual CNcbiOstream & GetBlobOStream(size_t blob_size, TBlobOStreamFlags flags=0, size_t buf_size=0)=0
Get Blob output stream.
virtual void SendSql(const string &sql)=0
Sends one or more SQL statements to the SQL server.
EBlobOStreamFlags
EBlobOStreamFlags –.
Definition: dbapi.hpp:84
@ eRowsPerBatch
Definition: dbapi.hpp:676
@ eKilobytesPerBatch
Definition: dbapi.hpp:677
@ eCheckConstraints
Definition: dbapi.hpp:679
@ eDisableLog
Disables log.
Definition: dbapi.hpp:73
@ eEnableLog
Enables log.
Definition: dbapi.hpp:74
@ fBOS_UseTransaction
Use a (sub)transaction (committed once all data's been sent successfully, rolled back for unrecoverab...
Definition: dbapi.hpp:93
@ fBOS_SkipLogging
Definition: dbapi.hpp:94
EDB_ResType
EDB_ResType::
Definition: interfaces.hpp:386
EDB_Type
Definition: types.hpp:52
#define NCBI_DEPRECATED
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:149
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:146
#define kEmptyStr
Definition: ncbistr.hpp:123
enum ENcbiOwnership EOwnership
Ownership relations between objects.
#define NCBI_DBAPI_EXPORT
Definition: ncbi_export.h:432
<!DOCTYPE HTML >< html > n< header > n< title > PubSeq Gateway Help Page</title > n< style > n table
use only n Cassandra database for the lookups</td > n</tr > n< tr > n< td > yes</td > n< td > do not use tables BIOSEQ_INFO and BLOB_PROP in the Cassandra database
char * buf
int i
string Execute(const string &cmmd, const vector< string > &args, const string &data=kEmptyStr)
mdb_mode_t mode
Definition: lmdb++.h:38
const struct ncbi::grid::netcache::search::fields::SIZE size
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx.
Modified on Tue May 28 05:52:48 2024 by modify_doxy.py rev. 669887