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

Go to the SVN repository for this file.

1 #ifndef DBAPI_DRIVER___INTERFACES__HPP
2 #define DBAPI_DRIVER___INTERFACES__HPP
3 
4 /* $Id: interfaces.hpp 93420 2021-04-12 13:27:11Z ucko $
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: Vladimir Soussov
30  *
31  * File Description: Data Server interfaces
32  *
33  */
34 
35 #include <corelib/ncbi_param.hpp>
37 
38 #include <dbapi/driver/types.hpp>
40 
41 #ifdef NCBI_OS_UNIX
42 # include <unistd.h>
43 #endif
44 
45 #include <map>
46 
47 
48 // Visual Studio 2013 and 2015 overreact on deprecated methods
49 #if defined(_MSC_VER) && _MSC_VER < 1920
50  #pragma warning(push)
51  #pragma warning(disable : 4996)
52 #endif
53 
54 
55 /** @addtogroup DbInterfaces
56  *
57  * @{
58  */
59 
60 
62 
63 
64 class I_BaseCmd;
65 
66 class I_DriverContext;
67 
68 class I_Connection;
69 class I_Result;
70 class I_LangCmd;
71 class I_RPCCmd;
72 class I_BCPInCmd;
73 class I_CursorCmd;
74 class I_SendDataCmd;
75 
76 class CDB_Connection;
77 class CDB_Result;
78 class CDB_LangCmd;
79 class CDB_RPCCmd;
80 class CDB_BCPInCmd;
81 class CDB_CursorCmd;
82 class CDB_SendDataCmd;
84 
85 class IConnValidator;
86 
87 namespace impl
88 {
89  class CResult;
90  class CBaseCmd;
91  class CSendDataCmd;
92 }
93 
94 
96 {
97 public:
98  enum ENameFormat {
100  eQMarkName, // '...WHERE name=?'
101  eNumericName, // '...WHERE name=:1'
102  eNamedName, // '...WHERE name=:name'
103  eFormatName, // ANSI C printf format codes, e.g. '...WHERE name=%s'
104  eSQLServerName // '...WHERE name=@name'
105  };
106 
107 public:
108  CDBParamVariant(int pos);
109  CDBParamVariant(unsigned int pos);
110  CDBParamVariant(const char* name);
111  CDBParamVariant(const string& name);
112  ~CDBParamVariant(void);
113 
114 public:
115  bool IsPositional(void) const
116  {
117  return m_IsPositional;
118  }
119  unsigned int GetPosition(void) const
120  {
121  return m_Pos;
122  }
123 
124 
125  ENameFormat GetFormat(void) const
126  {
127  return m_Format;
128  }
129  const string& GetName(void) const
130  {
131  return m_Name;
132  }
133  string GetName(ENameFormat format) const;
134 
135  static string MakePlainName(const CTempString& name);
136 
137 private:
138  static CTempString MakeName(const CTempString& name, ENameFormat& format);
139 
140 private:
142  unsigned int m_Pos;
144  const string m_Name;
145 };
146 
147 
148 
149 /////////////////////////////////////////////////////////////////////////////
150 ///
151 /// CDBParams
152 
154 {
155 public:
156  virtual ~CDBParams(void);
157 
158 public:
159  enum EDirection {eIn, eOut, eInOut};
160 
161  /// Get total number of columns in resultset.
162  ///
163  /// @return
164  /// total number of columns in resultset
165  virtual unsigned int GetNum(void) const = 0;
166 
167  /// Get name of column.
168  /// This method is returning const reference because meta-info MUST be
169  /// cached for performance reasons.
170  ///
171  /// @param param
172  /// Column number or name
173  virtual const string& GetName(
174  const CDBParamVariant& param,
177 
178  /// @brief
179  ///
180  /// @param param
181  /// Column number or name
182  ///
183  /// @return
184  /// Number of a columnn, which is corresponding to a name.
185  virtual unsigned int GetIndex(const CDBParamVariant& param) const = 0;
186 
187  /// Get maximum size in bytes for column.
188  ///
189  /// @param col
190  /// Column number or name
191  ///
192  /// @return
193  /// Max number of bytes needed to hold the returned data.
194  virtual size_t GetMaxSize(const CDBParamVariant& param) const = 0;
195 
196  /// Get data type for column in the resultset.
197  ///
198  /// @param param
199  /// Column number or name
200  virtual EDB_Type GetDataType(const CDBParamVariant& param) const = 0;
201 
202  /// Get value of column.
203  ///
204  /// @param param
205  /// Column number or name
206  virtual const CDB_Object* GetValue(const CDBParamVariant& param) const = 0;
207 
208  /// Get parameter's direction (in/out/inout).
209  ///
210  /// @param param
211  /// Column number or name
212  virtual EDirection GetDirection(const CDBParamVariant& param) const = 0;
213 
214  /// This method stores pointer to data.
215  ///
216  /// @param param
217  /// Column number or name
218  ///
219  /// @param value
220  /// Binded object
221  ///
222  /// @param out_param
223  /// true if this parameter is an output parameter
224  virtual CDBParams& Bind(
225  const CDBParamVariant& param,
226  CDB_Object* value,
227  bool out_param = false
228  );
229 
230  /// This method stores copy of data.
231  ///
232  /// @param param
233  /// Column number or name
234  ///
235  /// @param value
236  /// Binded object
237  ///
238  /// @param out_param
239  /// true if this parameter is an output parameter
240  virtual CDBParams& Set(
241  const CDBParamVariant& param,
242  CDB_Object* value,
243  bool out_param = false
244  );
245 
246  /// Yield a lightweight copy of these parameters, sharing
247  /// representations for variable-length datatypes.
248  virtual CDBParams* SemiShallowClone(void) const = 0;
249 };
250 
251 
252 /////////////////////////////////////////////////////////////////////////////
253 ///
254 /// CDBConnParams::
255 ///
256 
258 {
259 public:
260  CDBConnParams(void);
261  virtual ~CDBConnParams(void);
262 
263 public:
264  enum EServerType {
265  eUnknown, //< Server type is not known
266  eMySQL, //< MySQL server
267  eSybaseOpenServer, //< Sybase Open server
268  eSybaseSQLServer, //< Sybase SQL server
269  eMSSqlServer //< Microsoft SQL server
270  };
271 
272  virtual string GetDriverName(void) const = 0;
273  virtual Uint4 GetProtocolVersion(void) const = 0;
274  virtual EEncoding GetEncoding(void) const = 0;
275 
276  virtual string GetServerName(void) const = 0;
277  virtual string GetDatabaseName(void) const = 0;
278  virtual string GetUserName(void) const = 0;
279  virtual string GetPassword(void) const = 0;
280 
281  virtual EServerType GetServerType(void) const = 0;
282  virtual Uint4 GetHost(void) const = 0;
283  virtual Uint2 GetPort(void) const = 0;
284 
285  virtual CRef<IConnValidator> GetConnValidator(void) const = 0;
286  virtual const impl::CDBHandlerStack& GetOpeningMsgHandlers(void) const = 0;
287 
288  /// Parameters, which are not listed above explicitly, should be retrieved via
289  /// SetParam() method.
290  virtual string GetParam(const string& key) const = 0;
291 
292 protected:
293  void SetChildObj(const CDBConnParams& child_obj) const
294  {
296  m_ChildObj = &child_obj;
297  }
298  void ReleaseChildObj(void) const
299  {
300  m_ChildObj = NULL;
301  }
302 
303 protected:
304  const CDBConnParams& GetThis(void) const
305  {
306  if (m_ChildObj) {
307  return m_ChildObj->GetThis();
308  }
309 
310  return *this;
311  }
312 
313 private:
314  // Non-copyable.
317 
318 private:
319  mutable const CDBConnParams* m_ChildObj;
320 
321  friend class CDBConnParamsDelegate;
322 };
323 
324 
325 /////////////////////////////////////////////////////////////////////////////
327 {
328 public:
329  CDBConnParamsDelegate(const CDBConnParams& other);
330  virtual ~CDBConnParamsDelegate(void);
331 
332 public:
333  virtual string GetDriverName(void) const;
334  virtual Uint4 GetProtocolVersion(void) const;
335  virtual EEncoding GetEncoding(void) const;
336 
337  virtual string GetServerName(void) const;
338  virtual string GetDatabaseName(void) const;
339  virtual string GetUserName(void) const;
340  virtual string GetPassword(void) const;
341 
342  virtual EServerType GetServerType(void) const;
343  virtual Uint4 GetHost(void) const;
344  virtual Uint2 GetPort(void) const;
345 
346  virtual CRef<IConnValidator> GetConnValidator(void) const;
347  virtual const impl::CDBHandlerStack& GetOpeningMsgHandlers(void) const;
348 
349  virtual string GetParam(const string& key) const;
350 
351 private:
352  // Non-copyable.
354  CDBConnParamsDelegate& operator =(const CDBConnParamsDelegate& other);
355 
356 private:
358 };
359 
360 
361 /////////////////////////////////////////////////////////////////////////////
362 ///
363 /// I_BlobDescriptor::
364 ///
365 /// BLOB descriptor.
366 ///
367 
369 {
370 public:
371  virtual int DescriptorType(void) const = 0;
372  virtual ~I_BlobDescriptor(void);
373 };
374 
375 // historical name
377 
378 
379 /////////////////////////////////////////////////////////////////////////////
380 ///
381 /// EDB_ResType::
382 ///
383 /// Type of result set
384 ///
385 
392 };
393 
394 
395 /////////////////////////////////////////////////////////////////////////////
396 ///
397 /// CParamStmt::
398 /// Parametrized statement.
399 
401 {
402 public:
403  CParamStmt(void);
404  virtual ~CParamStmt(void);
405 
406 public:
407  /// Get meta-information about binded parameters.
408  virtual CDBParams& GetBindParams(void) = 0;
409 };
410 
411 /////////////////////////////////////////////////////////////////////////////
412 ///
413 /// CParamRecordset::
414 /// Parametrized recordset.
415 
417 {
418 public:
419  CParamRecordset(void);
420  virtual ~CParamRecordset(void);
421 
422 public:
423  /// Get meta-information about defined parameters.
424  virtual CDBParams& GetDefineParams(void) = 0;
425 };
426 
427 
428 /////////////////////////////////////////////////////////////////////////////
429 ///
430 /// I_BaseCmd::
431 ///
432 /// Abstract base class for most "command" interface classes.
433 ///
434 
436 {
437 public:
438  I_BaseCmd(void);
439  virtual ~I_BaseCmd(void);
440 
441 public:
442  /// Send command to the server
443  virtual bool Send(void) = 0;
444  /// Implementation-specific.
445  /// @deprecated
446  virtual bool WasSent(void) const = 0;
447 
448  /// Cancel the command execution
449  virtual bool Cancel(void) = 0;
450  /// Implementation-specific.
451  /// @deprecated
452  virtual bool WasCanceled(void) const = 0;
453 
454  /// Get result set
455  virtual CDB_Result* Result(void) = 0;
456  virtual bool HasMoreResults(void) const = 0;
457 
458  // Check if command has failed
459  virtual bool HasFailed(void) const = 0;
460 
461  /// Get the number of rows affected by the command
462  /// Special case: negative on error or if there is no way that this
463  /// command could ever affect any rows (like PRINT).
464  virtual int RowCount(void) const = 0;
465 
466  /// Dump the results of the command
467  /// if result processor is installed for this connection, it will be called for
468  /// each result set
469  virtual void DumpResults(void) = 0;
470 };
471 
472 
473 /////////////////////////////////////////////////////////////////////////////
474 ///
475 /// I_LangCmd::
476 /// I_RPCCmd::
477 /// I_BCPInCmd::
478 /// I_CursorCmd::
479 /// I_SendDataCmd::
480 ///
481 /// "Command" interface classes.
482 ///
483 
484 
486 {
487 public:
488  I_LangCmd(void);
489  virtual ~I_LangCmd(void);
490 
491 protected:
492  /// Add more text to the language command
493  /// @deprecated
494  virtual bool More(const string& query_text) = 0;
495 };
496 
497 
498 
500 {
501 public:
502  I_RPCCmd(void);
503  virtual ~I_RPCCmd(void);
504 
505 protected:
506  /// Set the "recompile before execute" flag for the stored proc
507  /// Implementation-specific.
508  virtual void SetRecompile(bool recompile = true) = 0;
509 
510  /// Get a name of the procedure.
511  virtual const string& GetProcName(void) const = 0;
512 };
513 
514 
515 
517 {
518 public:
519  I_BCPInCmd(void);
520  virtual ~I_BCPInCmd(void);
521 
522 protected:
523  /// Send row to the server
524  virtual bool SendRow(void) = 0;
525 
526  /// Complete batch -- to store all rows transferred by far in this batch
527  /// into the table
528  virtual bool CompleteBatch(void) = 0;
529 
530  /// Cancel the BCP command
531  virtual bool Cancel(void) = 0;
532 
533  /// Complete the BCP and store all rows transferred in last batch into
534  /// the table
535  virtual bool CompleteBCP(void) = 0;
536 };
537 
538 
539 
541 {
542 public:
543  I_CursorCmd(void);
544  virtual ~I_CursorCmd(void);
545 
546 protected:
547  /// Open the cursor.
548  /// Return NULL if cursor resulted in no data.
549  /// Throw exception on error.
550  virtual CDB_Result* Open(void) = 0;
551 
552  /// Update the last fetched row.
553  /// NOTE: the cursor must be declared for update in CDB_Connection::Cursor()
554  virtual bool Update(const string& table_name, const string& upd_query) = 0;
555 
556  /// @deprecated
557  /// Please use I_Connection::SendData instead.
558  /// @sa
559  /// I_Connection::SendData
561  virtual bool UpdateBlob(unsigned int item_num, CDB_Stream& data,
562  bool log_it = true) = 0;
563 
564  /// @deprecated
565  /// Please use I_Connection::SendData instead.
566  /// @sa
567  /// I_Connection::SendData
569  bool UpdateTextImage(unsigned int item_num, CDB_Stream& data,
570  bool log_it = true);
571 
572  /// @brief
573  /// Create send-data command.
574  ///
575  /// @param item_num
576  /// Column number to rewrite.
577  /// @param size
578  /// Maximal data size.
579  /// @param log_it
580  /// Log LOB operation if this value is set to true.
581  /// @param discard_results
582  /// Discard all resultsets that might be returned from server
583  /// if this value is set to true.
584  ///
585  /// @return
586  /// Newly created send-data object.
587  /// @deprecated
588  /// Please use I_Connection::SendDataCmd instead.
589  /// @sa
590  /// I_Connection::SendDataCmd
592  virtual CDB_SendDataCmd* SendDataCmd(unsigned int item_num, size_t size,
593  bool log_it = true,
594  bool discard_results = true) = 0;
595  /// Delete the last fetched row.
596  /// NOTE: the cursor must be declared for delete in CDB_Connection::Cursor()
597  virtual bool Delete(const string& table_name) = 0;
598 
599  /// Get the number of fetched rows
600  /// Special case: negative on error or if there is no way that this
601  /// command could ever affect any rows (like PRINT).
602  virtual int RowCount(void) const = 0;
603 
604  /// Close the cursor.
605  /// Return FALSE if the cursor is closed already (or not opened yet)
606  virtual bool Close(void) = 0;
607 };
608 
609 
610 
612 {
613 public:
614  I_SendDataCmd(void);
615  virtual ~I_SendDataCmd(void);
616 
617 protected:
618  /// Send chunk of data to the server.
619  /// Return number of bytes actually transferred to server.
620  virtual size_t SendChunk(const void* pChunk, size_t nofBytes) = 0;
621  virtual bool Cancel(void) = 0;
622 };
623 
624 
625 
626 /////////////////////////////////////////////////////////////////////////////
627 ///
628 /// I_Result::
629 ///
630 
632 {
633 public:
634  I_Result(void);
635  virtual ~I_Result(void);
636 
637 public:
638  enum EGetItem {eAppendLOB, eAssignLOB};
639 
640  /// @brief
641  /// Get type of the result
642  ///
643  /// @return
644  /// Result type
645  virtual EDB_ResType ResultType(void) const = 0;
646 
647  /// Get meta-information about rows in resultset.
648  virtual const CDBParams& GetDefineParams(void) const = 0;
649 
650  /// Get # of items (columns) in the result
651  /// @brief
652  /// Get # of items (columns) in the result.
653  ///
654  /// @return
655  /// Number of items (columns) in the result.
656  virtual unsigned int NofItems(void) const = 0;
657 
658  /// @brief
659  /// Get name of a result item.
660  ///
661  /// @param item_num
662  /// Number of item, starting from 0.
663  ///
664  /// @return
665  /// NULL if "item_num" >= NofItems(), otherwise item name.
666  virtual const char* ItemName(unsigned int item_num) const = 0;
667 
668  /// @brief
669  /// Get size (in bytes) of a result item.
670  ///
671  /// @param item_num
672  /// Number of item, starting from 0.
673  ///
674  /// @return
675  /// Return zero if "item_num" >= NofItems().
676  virtual size_t ItemMaxSize(unsigned int item_num) const = 0;
677 
678  /// @brief
679  /// Get datatype of a result item.
680  ///
681  /// @param item_num
682  /// Number of item, starting from 0.
683  ///
684  /// @return
685  /// Return 'eDB_UnsupportedType' if "item_num" >= NofItems().
686  virtual EDB_Type ItemDataType(unsigned int item_num) const = 0;
687 
688  /// @brief
689  /// Fetch next row
690  ///
691  /// @return
692  /// - true if a record was fetched.
693  /// - false if no more record can be fetched.
694  virtual bool Fetch(void) = 0;
695 
696  /// @brief
697  /// Return current item number we can retrieve (0,1,...)
698  ///
699  /// @return
700  /// Return current item number we can retrieve (0,1,...)
701  /// Return "-1" if no more items left (or available) to read.
702  virtual int CurrentItemNo(void) const = 0;
703 
704  /// @brief
705  /// Return number of columns in the recordset.
706  ///
707  /// @return
708  /// number of columns in the recordset.
709  virtual int GetColumnNum(void) const = 0;
710 
711  /// @brief
712  /// Get a result item (you can use either GetItem or ReadItem).
713  ///
714  /// @param item_buf
715  /// If "item_buf" is not NULL, then use "*item_buf" (its type should be
716  /// compatible with the type of retrieved item!) to retrieve the item to;
717  /// otherwise allocate new "CDB_Object".
718  /// If the existing "item_buf" has a BLOB type (CDB_Image, CDB_Text,
719  /// CDB_VarBinaryMax, or CDB_VarCharMax), the value will be *appended*
720  /// to the "item_buf" by default (policy == eAppendLOB).
721  ///
722  /// @param policy
723  /// Data retrieval policy. If policy == eAppendLOB *and* "item_buf" has a
724  /// BLOB type (CDB_Image, CDB_Text, CDB_VarBinaryMax, or CDB_VarCharMax),
725  /// data will be *appended* to the end of previously assigned data.
726  /// Otherwise (policy == eAssignLOB or "item_buf" has some other type),
727  /// the new value will be *assigned* to the "item_buf" object.
728  ///
729  /// @return
730  /// a result item
731  ///
732  /// @sa
733  /// ReadItem, SkipItem
734  virtual CDB_Object* GetItem(CDB_Object* item_buf = 0, EGetItem policy = eAppendLOB) = 0;
735 
736  /// @brief
737  /// Read a result item body (for BLOB columns, mostly).
738  /// Throw an exception on any error.
739  ///
740  /// @param buffer
741  /// Buffer to fill with data.
742  /// @param buffer_size
743  /// Buffere size.
744  /// @param is_null
745  /// Set "*is_null" to TRUE if the item is <NULL>.
746  ///
747  /// @return
748  /// number of successfully read bytes.
749  ///
750  /// @sa
751  /// GetItem, SkipItem
752  virtual size_t ReadItem(void* buffer, size_t buffer_size,
753  bool* is_null = 0) = 0;
754 
755  /// @brief
756  /// Get a descriptor for a BLOB column (for SendData).
757  ///
758  /// @return
759  /// Return NULL if this result doesn't (or can't) have a BLOB descriptor.
760  ///
761  /// @note
762  /// You need to call ReadItem (maybe even with buffer_size == 0)
763  /// before calling this method!
764  /// @deprecated
765  /// Please use CDB_BlobDescriptor instead.
766  /// @sa
767  /// CDB_BlobDescriptor
770 
771  /// @deprecated
772  /// Please use CDB_BlobDescriptor instead.
773  /// @sa
774  /// CDB_BlobDescriptor
776  I_BlobDescriptor* GetImageOrTextDescriptor(void);
777 
778  /// @brief
779  /// Skip result item
780  ///
781  /// @return
782  /// TRUE on success.
783  ///
784  /// @sa
785  /// GetItem, ReadItem
786  virtual bool SkipItem(void) = 0;
787 };
788 
789 
790 /////////////////////////////////////////////////////////////////////////////
791 ///
792 /// I_DriverContext::
793 ///
794 
797 typedef NCBI_PARAM_TYPE(dbapi, conn_use_encrypt_data) TDbapi_ConnUseEncryptData;
798 
799 
800 class CDBConnParams;
801 
803 {
804 protected:
805  I_DriverContext(void);
806 
807 public:
808  virtual ~I_DriverContext(void);
809 
810 
811  /// Connection mode
813  fBcpIn = 0x1, //< Enable BCP
814  fPasswordEncrypted = 0x2, //< Encript password
815  fDoNotConnect = 0x4 //< Use just connections from NotInUse pool
816  // all driver-specific mode flags > 0x100
817  };
818 
819  typedef int TConnectionMode; //< holds a binary OR of "EConnectionMode"
820 
821 
822  /// Set login timeout.
823  ///
824  /// This timeout limits how long each login attempt can take. (If you've
825  /// enabled retrying, the total time can be longer.)
826  /// @param nof_secs
827  /// Timeout in seconds. If "nof_secs" is zero or is "too big"
828  /// (depends on the underlying DB API), then set the timeout to infinite.
829  /// @return
830  /// FALSE on error.
831  ///
832  /// @sa
833  /// GetLoginTimeout, SetTimeout, CDB_Connection::SetTimeout, CDB_Connection::SetCancelTimeout
834  virtual bool SetLoginTimeout(unsigned int nof_secs = 0) = 0;
835 
836  /// Set connection timeout.
837  ///
838  /// This timeout limits how long each query or the like can take by default
839  /// in subsequently created connections.
840  /// @param nof_secs
841  /// Timeout in seconds. If "nof_secs" is zero or is "too big"
842  /// (depends on the underlying DB API), then set the timeout to infinite.
843  /// @return
844  /// FALSE on error.
845  ///
846  /// @sa
847  /// GetTimeout, SetLoginTimeout, CDB_Connection::SetTimeout, CDB_Connection::SetCancelTimeout
848  virtual bool SetTimeout(unsigned int nof_secs = 0) = 0;
849 
850  /// Get login timeout
851  ///
852  /// This timeout limits how long each login attempt can take. (If you've
853  /// enabled retrying, the total time can be longer.)
854  /// @return
855  /// Login timeout.
856  /// @sa
857  /// SetLoginTimeout, GetTimeout, CDB_Connection::GetTimeout, CDB_Connection::GetCancelTimeout
858  virtual unsigned int GetLoginTimeout(void) const = 0;
859 
860  /// Get connection timeout
861  ///
862  /// This timeout limits how long each query or the like can take by default
863  /// in subsequently created connections.
864  /// @return
865  /// Connection timeout.
866  ///
867  /// @sa
868  /// SetTimeout, GetLoginTimeout, CDB_Connection::GetTimeout, CDB_Connection::GetCancelTimeout
869  virtual unsigned int GetTimeout(void) const = 0;
870 
871  /// Set maximal size for BLOB data.
872  ///
873  /// @param nof_bytes
874  /// Maximal size for BLOB data ([N]TEXT, IMAGE, [N]VARCHAR(MAX),
875  /// VARBINARY(MAX), XML). BLOBs exceeding this size will be truncated.
876  /// @return
877  /// FALSE on error (e.g. if "nof_bytes" is too big).
878  virtual bool SetMaxBlobSize(size_t nof_bytes) = 0;
879  bool SetMaxTextImageSize(size_t n) { return SetMaxBlobSize(n); }
880 
881 
882  /// @brief
883  /// Create new connection to specified server (or service) within this context.
884  ///
885  /// @param srv_name
886  /// Server/Service name. This parameter can be a SERVER name (host name,
887  /// DNS alias name, or one of the names found in interfaces file) or an
888  /// IP address. This parameter can also be a SERVICE name, which is
889  /// defined by Load Balancer framework. In order to enable using of LB
890  /// service names you have to call DBLB_INSTALL_DEFAULT() macro before
891  /// any other DBAPI method.
892  /// @param user_name
893  /// User name.
894  /// @param passwd
895  /// User password.
896  /// @param mode
897  /// Connection mode.
898  /// @param reusable
899  /// If set to TRUE, then return connection into a connection pool on deletion.
900  /// @param pool_name
901  /// Name of a pool to which this connection is going to belong.
902  ///
903  /// @return
904  /// Connection object on success, NULL on error.
905  ///
906  /// NOTE:
907  ///
908  /// It is your responsibility to delete the returned connection object.
909  /// reusable - controls connection pooling mechanism. If it is set to true
910  /// then a connection will be added to a pool of connections instead of
911  /// closing.
912  ///
913  /// srv_name, user_name and passwd may be set to empty string.
914  ///
915  /// If pool_name is provided then connection will be taken from a pool
916  /// having this name if a pool is not empty.
917  ///
918  /// It is your responsibility to put connections with the same
919  /// server/user/password values in a pool.
920  ///
921  /// If a pool name is not provided but a server name (srv_name) is provided
922  /// instead then connection with the same name will be taken from a pool of
923  /// connections if a pool is not empty.
924  ///
925  /// If a pool is empty then new connection will be created unless you passed
926  /// mode = fDoNotConnect. In this case NULL will be returned.
927  ///
928  /// If you did not provide either a pool name or a server name then NULL will
929  /// be returned.
931  const string& srv_name,
932  const string& user_name,
933  const string& passwd,
934  TConnectionMode mode,
935  bool reusable = false,
936  const string& pool_name = kEmptyStr);
937 
938  /// @brief
939  /// Create new connection to specified server (within this context).
940  ///
941  /// @param srv_name
942  /// Server/Service name. This parameter can be a SERVER name (host name,
943  /// DNS alias name, or one of the names found in interfaces file) or an
944  /// IP address. This parameter can also be a SERVICE name, which is
945  /// defined by Load Balancer framework. In order to enable using of LB
946  /// service names you have to call DBLB_INSTALL_DEFAULT() macro before
947  /// any other DBAPI method.
948  /// @param user_name
949  /// User name.
950  /// @param passwd
951  /// User password.
952  /// @param validator
953  /// Connection validation object.
954  /// @param mode
955  /// Connection mode.
956  /// @param reusable
957  /// If set to true put connection into a connection pool on deletion.
958  /// @param pool_name
959  /// Name of a pool to which this connection is going to belong.
960  ///
961  /// @return
962  /// Connection object on success, NULL on error.
963  ///
964  /// NOTE:
965  ///
966  /// It is your responsibility to delete the returned connection object.
967  /// reusable - controls connection pooling mechanism. If it is set to true
968  /// then a connection will be added to a pool of connections instead of
969  /// closing.
970  ///
971  /// srv_name, user_name and passwd may be set to empty string.
972  ///
973  /// If pool_name is provided then connection will be taken from a pool
974  /// having this name if a pool is not empty.
975  ///
976  /// It is your responsibility to put connections with the same
977  /// server/user/password values in a pool.
978  ///
979  /// If a pool name is not provided but a server name (srv_name) is provided
980  /// instead then connection with the same name will be taken from a pool of
981  /// connections if a pool is not empty.
982  ///
983  /// If a pool is empty then new connection will be created unless you passed
984  /// mode = fDoNotConnect. In this case NULL will be returned.
985  ///
986  /// If you did not provide either a pool name or a server name then NULL will
987  /// be returned.
988  CDB_Connection* ConnectValidated(
989  const string& srv_name,
990  const string& user_name,
991  const string& passwd,
992  IConnValidator& validator,
993  TConnectionMode mode = 0,
994  bool reusable = false,
995  const string& pool_name = kEmptyStr);
996 
997  /// @brief
998  /// Create connection object using Load Balancer / connection factory.
999  ///
1000  /// @param params
1001  /// Connection parameters.
1002  ///
1003  /// @return
1004  /// Connection object.
1005  virtual CDB_Connection* MakeConnection(const CDBConnParams& params) = 0;
1006 
1007  /// @brief
1008  /// Return number of currently open connections in this context.
1009  ///
1010  /// @param srv_name
1011  /// Server/Service name. If not empty, then return # of connection
1012  /// open to that server.
1013  /// @param pool_name
1014  /// Name of connection pool.
1015  ///
1016  /// @return
1017  /// Return number of currently open connections in this context.
1018  /// If "srv_name" is not NULL, then return # of conn. open to that server.
1019  virtual unsigned int NofConnections(const string& srv_name = "",
1020  const string& pool_name = "")
1021  const = 0;
1022  virtual unsigned int NofConnections(const TSvrRef& svr_ref,
1023  const string& pool_name = "") const = 0;
1024 
1025  /// @brief
1026  /// Add message handler "h" to process 'context-wide' (not bound
1027  /// to any particular connection) error messages.
1028  ///
1029  /// @param h
1030  /// Error message handler.
1031  /// @param ownership
1032  /// If set to eNoOwnership, it is user's responsibility to unregister
1033  /// and delete the error message handler.
1034  /// If set to eTakeOwnership, then DBAPI will take ownership of the
1035  /// error message handler and delete it itself.
1036  ///
1037  /// @sa
1038  /// PopCntxMsgHandler()
1040  EOwnership ownership = eNoOwnership) = 0;
1041 
1042  /// @brief
1043  /// Remove message handler "h" and all handlers above it in the stack.
1044  ///
1045  /// @param h
1046  /// Error message handler to be removed.
1047  ///
1048  /// @sa
1049  /// PushCntxMsgHandler()
1050  virtual void PopCntxMsgHandler(CDB_UserHandler* h) = 0;
1051 
1052  /// @brief
1053  /// Add `per-connection' err.message handler "h" to the stack of default
1054  /// handlers which are inherited by all newly created connections.
1055  ///
1056  /// @param h
1057  /// Error message handler.
1058  /// @param ownership
1059  /// If set to eNoOwnership, it is user's responsibility to unregister
1060  /// and delete the error message handler.
1061  /// If set to eTakeOwnership, then DBAPI will take ownership of the
1062  /// error message handler and delete it itself.
1063  ///
1064  /// @sa
1065  /// PopDefConnMsgHandler()
1067  EOwnership ownership = eNoOwnership) = 0;
1068 
1069  /// @brief
1070  /// Remove `per-connection' mess. handler "h" and all above it in the stack.
1071  ///
1072  /// @param h
1073  /// Error message handler.
1074  ///
1075  /// @sa
1076  /// PushDefConnMsgHandler()
1078 
1079  /// Report if the driver supports this functionality
1081  eBcp, //< Is able to run BCP operations.
1082  eReturnBlobDescriptors, //< Is able to return BlobDescriptor.
1083  eReturnITDescriptors = eReturnBlobDescriptors,
1084  eReturnComputeResults //< Is able to return compute results.
1085  };
1086 
1087  /// @brief
1088  /// Check if a driver is acle to provide necessary functionality.
1089  ///
1090  /// @param cpb
1091  /// Functionality to query about.
1092  ///
1093  /// @return
1094  /// - true if functionality is present
1095  /// - false if no such functionality.
1096  virtual bool IsAbleTo(ECapability cpb) const = 0;
1097 
1098  /// @brief
1099  /// Close reusable deleted connections for specified server and/or pool.
1100  ///
1101  /// @param srv_name
1102  /// Server/Service name.
1103  /// @param pool_name
1104  /// Name of connection pool.
1105  /// @param max_closings
1106  /// Maximum number of connections to close now.
1107  virtual void CloseUnusedConnections(const string& srv_name = kEmptyStr,
1108  const string& pool_name = kEmptyStr,
1109  unsigned int max_closings = kMax_UInt)
1110  = 0;
1111 
1112  /// @brief
1113  /// Set application name.
1114  ///
1115  /// @param app_name
1116  /// defines the application name that a connection will use when
1117  /// connecting to a server.
1118  ///
1119  /// @sa
1120  /// GetApplicationName(), InitApplicationName()
1121  virtual void SetApplicationName(const string& app_name) = 0;
1122 
1123  /// @brief
1124  /// Return application name.
1125  ///
1126  /// @return
1127  /// Application name.
1128  ///
1129  /// @sa
1130  /// InitApplicationName(), SetApplicationName()
1131  virtual string GetApplicationName(void) const = 0;
1132 
1133  /// @brief
1134  /// Explicitly auto-initialize the application name, if necessary.
1135  ///
1136  /// @sa
1137  /// GetApplicationName(), SetApplicationName()
1138  virtual void InitApplicationName(void)
1139  { }
1140 
1141  /// @brief
1142  /// Set host name.
1143  ///
1144  /// @param host_name
1145  /// Host name
1146  ///
1147  /// @sa
1148  /// GetHostName()
1149  virtual void SetHostName(const string& host_name) = 0;
1150 
1151  /// @brief
1152  /// Get host name.
1153  ///
1154  /// @return
1155  /// Host name.
1156  ///
1157  /// @sa
1158  /// SetHostName()
1159  virtual string GetHostName(void) const = 0;
1160 
1161  virtual string GetDriverName(void) const;
1162 
1163 protected:
1164  /// @brief
1165  /// Create connection object WITHOUT using of Load Balancer / connection factory.
1166  ///
1167  /// @param params
1168  /// Connection parameters.
1169  ///
1170  /// @return
1171  /// Connection object.
1173 
1174 private:
1175  friend class IDBConnectionFactory;
1176 };
1177 
1178 
1179 
1180 /////////////////////////////////////////////////////////////////////////////
1181 ///
1182 /// I_Connection::
1183 ///
1184 
1186 {
1187 public:
1188  I_Connection(void);
1189  virtual ~I_Connection(void);
1190 
1191 protected:
1192  /// @brief
1193  /// Check out if connection is alive.
1194  ///
1195  /// This function doesn't ping the server,
1196  /// it just checks the status of connection which was set by the last
1197  /// i/o operation.
1198  ///
1199  /// @return
1200  /// - true if connection is alive
1201  /// - false in other case.
1202  virtual bool IsAlive(void) = 0;
1203 
1204  /// These methods: LangCmd(), RPC(), BCPIn(), Cursor() and SendDataCmd()
1205  /// create and return a "command" object, register it for later use with
1206  /// this (and only this!) connection.
1207  /// On error, an exception will be thrown (they never return NULL!).
1208  /// It is the user's responsibility to delete the returned "command" object.
1209 
1210  /// Language command
1211  virtual CDB_LangCmd* LangCmd(const string& lang_query) = 0;
1212  /// Remote procedure call
1213  virtual CDB_RPCCmd* RPC(const string& rpc_name) = 0;
1214  /// "Bulk copy in" command
1215  virtual CDB_BCPInCmd* BCPIn(const string& table_name) = 0;
1216  /// Cursor
1217  virtual CDB_CursorCmd* Cursor(const string& cursor_name,
1218  const string& query,
1219  unsigned int batch_size) = 0;
1220  CDB_CursorCmd* Cursor(const string& cursor_name,
1221  const string& query)
1222  {
1223  return Cursor(cursor_name, query, 1);
1224  }
1225  /// @brief
1226  /// Create send-data command.
1227  ///
1228  /// @param desc
1229  /// Lob descriptor.
1230  /// @param data_size
1231  /// Maximal data size.
1232  /// @param log_it
1233  /// Log LOB operation if this value is set to true.
1234  /// @param discard_results
1235  /// Discard all resultsets that might be returned from server
1236  /// if this value is set to true.
1237  ///
1238  /// @return
1239  /// Newly created send-data object.
1240  ///
1241  /// @sa SendData
1243  size_t data_size,
1244  bool log_it = true,
1245  bool discard_results = true)
1246  = 0;
1247 
1248  /// @brief
1249  /// Shortcut to send text and image to the server without using the
1250  /// "Send-data" command (SendDataCmd)
1251  ///
1252  /// @param desc
1253  /// Lob descriptor.
1254  /// @param lob
1255  /// Large object -- [N]TEXT, IMAGE, [N]VARCHAR(MAX), or VARBINARY(MAX).
1256  /// @param log_it
1257  /// Log LOB operation if this value is set to true.
1258  ///
1259  /// @return
1260  /// - true on success.
1261  ///
1262  /// @sa
1263  /// SendDataCmd
1264  virtual bool SendData(I_BlobDescriptor& desc, CDB_Stream& lob,
1265  bool log_it = true) = 0;
1266 
1267  /// @brief
1268  /// Reset the connection to the "ready" state (cancel all active commands)
1269  ///
1270  /// @return
1271  /// - true on success.
1272  virtual bool Refresh(void) = 0;
1273 
1274  /// @brief
1275  /// Get the server name.
1276  ///
1277  /// @return
1278  /// Server/Service name.
1279  virtual const string& ServerName(void) const = 0;
1280 
1281  /// @brief
1282  /// Get the user user.
1283  ///
1284  /// @return
1285  /// User name.
1286  virtual const string& UserName(void) const = 0;
1287 
1288  /// @brief
1289  /// Get the password.
1290  ///
1291  /// @return
1292  /// Password value.
1293  virtual const string& Password(void) const = 0;
1294 
1295  /// @brief
1296  /// Get the database name.
1297  ///
1298  /// @return
1299  /// Password value.
1300  virtual const string& DatabaseName(void) const = 0;
1301 
1302  /// @brief
1303  /// Get the bitmask for the connection mode (BCP, secure login, ...)
1304  ///
1305  /// @return
1306  /// bitmask for the connection mode (BCP, secure login, ...)
1308 
1309  /// @brief
1310  /// Check if this connection is a reusable one
1311  ///
1312  /// @return
1313  /// - true if this connection is a reusable one.
1314  virtual bool IsReusable(void) const = 0;
1315 
1316  /// @brief
1317  /// Find out which connection pool this connection belongs to
1318  ///
1319  /// @return
1320  /// connection pool
1321  virtual const string& PoolName(void) const = 0;
1322 
1323  /// @brief
1324  /// Get pointer to the driver context
1325  ///
1326  /// @return
1327  /// pointer to the driver context
1328  virtual I_DriverContext* Context(void) const = 0;
1329 
1330  /// @brief
1331  /// Put the message handler into message handler stack
1332  ///
1333  /// @param h
1334  /// Error message handler.
1335  /// @param ownership
1336  /// If set to eNoOwnership, it is user's responsibility to unregister
1337  /// and delete the error message handler.
1338  /// If set to eTakeOwnership, then DBAPI will take ownership of the
1339  /// error message handler and delete it itself.
1340  ///
1341  /// @sa
1342  /// PopMsgHandler
1344  EOwnership ownership = eNoOwnership) = 0;
1345 
1346  /// @brief
1347  /// Remove the message handler (and all above it) from the stack
1348  ///
1349  /// @param h
1350  /// Error message handler.
1351  /// @sa
1352  /// PushMsgHandler
1353  virtual void PopMsgHandler(CDB_UserHandler* h) = 0;
1354 
1355  /// @brief
1356  /// Set new result-processor.
1357  ///
1358  /// @param rp
1359  /// New result-processor.
1360  ///
1361  /// @return
1362  /// Old result-processor
1364 
1365  /// Abort the connection
1366  ///
1367  /// @return
1368  /// TRUE - if succeeded, FALSE if not
1369  ///
1370  /// @note
1371  /// Attention: it is not recommended to use this method unless you
1372  /// absolutely have to. The expected implementation is - close
1373  /// underlying file descriptor[s] without destroing any objects
1374  /// associated with a connection.
1375  ///
1376  /// @sa
1377  /// Close
1378  virtual bool Abort(void) = 0;
1379 
1380  /// Close an open connection.
1381  /// This method will return connection (if it is created as reusable) to
1382  /// its connection pool
1383  ///
1384  /// @return
1385  /// TRUE - if succeeded, FALSE if not
1386  ///
1387  /// @sa
1388  /// Abort, I_DriverContext::Connect
1389  virtual bool Close(void) = 0;
1390 
1391  /// @brief
1392  /// Set connection timeout.
1393  ///
1394  /// This timeout limits how long each query or the like can take.
1395  /// @param nof_secs
1396  /// Number of seconds. If "nof_secs" is zero or is "too big"
1397  /// (depends on the underlying DB API), then set the timeout to infinite.
1398  virtual void SetTimeout(size_t nof_secs) = 0;
1399 
1400  /// Get connection timeout.
1401  ///
1402  /// This timeout limits how long each query or the like can take.
1403  virtual size_t GetTimeout(void) const = 0;
1404 
1405  /// Get interface for extra features that could be implemented in the driver.
1407 
1408 public:
1409  // Deprecated legacy methods.
1410 
1411  /// @deprecated
1412  CDB_LangCmd* LangCmd(const string& lang_query, unsigned int /*unused*/)
1413  {
1414  return LangCmd(lang_query);
1415  }
1416  /// @deprecated
1417  CDB_RPCCmd* RPC(const string& rpc_name, unsigned int /*unused*/)
1418  {
1419  return RPC(rpc_name);
1420  }
1421  /// @deprecated
1422  CDB_BCPInCmd* BCPIn(const string& table_name, unsigned int /*unused*/)
1423  {
1424  return BCPIn(table_name);
1425  }
1426  /// @deprecated
1427  CDB_CursorCmd* Cursor(const string& cursor_name,
1428  const string& query,
1429  unsigned int /*unused*/,
1430  unsigned int batch_size)
1431  {
1432  return Cursor(cursor_name, query, batch_size);
1433  }
1434 
1435 };
1436 
1437 
1439 
1440 
1441 
1442 /* @} */
1443 
1444 
1445 #if defined(_MSC_VER) && _MSC_VER < 1920
1446  #pragma warning(pop)
1447 #endif
1448 
1449 
1450 #endif /* DBAPI_DRIVER___INTERFACES__HPP */
CDBConnParams::
Definition: interfaces.hpp:258
CDBParams.
Definition: interfaces.hpp:154
CParamRecordset:: Parametrized recordset.
Definition: interfaces.hpp:417
CParamStmt:: Parametrized statement.
Definition: interfaces.hpp:401
CResult –.
Definition: Result.hpp:64
CTempString implements a light-weight string on top of a storage buffer whose lifetime management is ...
Definition: tempstr.hpp:65
IDBConnectionFactory.
I_BaseCmd::
Definition: interfaces.hpp:436
I_BlobDescriptor::
Definition: interfaces.hpp:369
I_ConnectionExtra.
I_Connection::
I_LangCmd:: I_RPCCmd:: I_BCPInCmd:: I_CursorCmd:: I_SendDataCmd::
Definition: interfaces.hpp:486
I_Result::
Definition: interfaces.hpp:632
static const char table_name[]
Definition: bcp.c:249
char data[12]
Definition: iconv.c:80
@ eNoOwnership
No ownership is assumed.
Definition: ncbi_types.h:135
#define NULL
Definition: ncbistd.hpp:225
bool IsPositional(void) const
Definition: interfaces.hpp:115
virtual bool Close(void)=0
Close the cursor.
virtual EEncoding GetEncoding(void) const =0
virtual CDB_Result * Open(void)=0
Open the cursor.
virtual bool IsAlive(void)=0
Check out if connection is alive.
virtual int CurrentItemNo(void) const =0
Return current item number we can retrieve (0,1,...)
typedef NCBI_PARAM_TYPE(dbapi, conn_use_encrypt_data) TDbapi_ConnUseEncryptData
virtual const string & PoolName(void) const =0
Find out which connection pool this connection belongs to.
virtual void PushDefConnMsgHandler(CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0
Add `per-connection' err.message handler "h" to the stack of default handlers which are inherited by ...
virtual EDB_Type GetDataType(const CDBParamVariant &param) const =0
Get data type for column in the resultset.
CDB_BCPInCmd * BCPIn(const string &table_name, unsigned int)
virtual const impl::CDBHandlerStack & GetOpeningMsgHandlers(void) const =0
virtual CDB_SendDataCmd * SendDataCmd(I_BlobDescriptor &desc, size_t data_size, bool log_it=true, bool discard_results=true)=0
Create send-data command.
virtual bool Cancel(void)=0
virtual CDB_CursorCmd * Cursor(const string &cursor_name, const string &query, unsigned int batch_size)=0
Cursor.
virtual CDB_Connection * MakePooledConnection(const CDBConnParams &params)=0
Create connection object WITHOUT using of Load Balancer / connection factory.
virtual CDB_RPCCmd * RPC(const string &rpc_name)=0
Remote procedure call.
CDB_LangCmd * LangCmd(const string &lang_query, unsigned int)
virtual bool HasMoreResults(void) const =0
virtual bool Cancel(void)=0
Cancel the command execution.
const CDBConnParams & GetThis(void) const
Definition: interfaces.hpp:304
virtual const string & GetName(const CDBParamVariant &param, CDBParamVariant::ENameFormat format=CDBParamVariant::eSQLServerName) const =0
Get name of column.
virtual size_t GetMaxSize(const CDBParamVariant &param) const =0
Get maximum size in bytes for column.
ECapability
Report if the driver supports this functionality.
NCBI_DBAPIDRIVER_EXPORT
I_DriverContext::
Definition: interfaces.hpp:795
virtual bool SendData(I_BlobDescriptor &desc, CDB_Stream &lob, bool log_it=true)=0
Shortcut to send text and image to the server without using the "Send-data" command (SendDataCmd)
CDB_CursorCmd * Cursor(const string &cursor_name, const string &query, unsigned int, unsigned int batch_size)
virtual size_t SendChunk(const void *pChunk, size_t nofBytes)=0
Send chunk of data to the server.
virtual CDB_BCPInCmd * BCPIn(const string &table_name)=0
"Bulk copy in" command
virtual const string & DatabaseName(void) const =0
Get the database name.
unsigned int m_Pos
Definition: interfaces.hpp:142
virtual unsigned int GetNum(void) const =0
Get total number of columns in resultset.
virtual string GetApplicationName(void) const =0
Return application name.
virtual bool Close(void)=0
Close an open connection.
virtual bool Update(const string &table_name, const string &upd_query)=0
Update the last fetched row.
virtual bool WasSent(void) const =0
Implementation-specific.
I_BlobDescriptor I_ITDescriptor
Definition: interfaces.hpp:376
virtual unsigned int GetTimeout(void) const =0
Get connection timeout.
CDB_CursorCmd * Cursor(const string &cursor_name, const string &query)
virtual int DescriptorType(void) const =0
virtual bool SendRow(void)=0
Send row to the server.
virtual EServerType GetServerType(void) const =0
CDBConnParams(void)
Definition: interfaces.cpp:42
virtual size_t GetTimeout(void) const =0
Get connection timeout.
virtual unsigned int NofItems(void) const =0
Get # of items (columns) in the result.
virtual CDBParams & GetBindParams(void)=0
Get meta-information about binded parameters.
virtual string GetPassword(void) const =0
virtual void DumpResults(void)=0
Dump the results of the command if result processor is installed for this connection,...
virtual CDB_LangCmd * LangCmd(const string &lang_query)=0
These methods: LangCmd(), RPC(), BCPIn(), Cursor() and SendDataCmd() create and return a "command" ob...
virtual I_DriverContext * Context(void) const =0
Get pointer to the driver context.
virtual bool SetLoginTimeout(unsigned int nof_secs=0)=0
Set login timeout.
virtual ~CParamRecordset(void)
Definition: interfaces.cpp:195
virtual const char * ItemName(unsigned int item_num) const =0
Get name of a result item.
virtual bool Abort(void)=0
Abort the connection.
virtual void InitApplicationName(void)
Explicitly auto-initialize the application name, if necessary.
virtual Uint4 GetProtocolVersion(void) const =0
void SetChildObj(const CDBConnParams &child_obj) const
Definition: interfaces.hpp:293
CDB_RPCCmd * RPC(const string &rpc_name, unsigned int)
virtual ~CParamStmt(void)
Definition: interfaces.cpp:203
virtual bool Fetch(void)=0
Fetch next row.
virtual CDBParams & GetDefineParams(void)=0
Get meta-information about defined parameters.
dbapi
Definition: interfaces.hpp:796
virtual bool Refresh(void)=0
Reset the connection to the "ready" state (cancel all active commands)
virtual I_DriverContext::TConnectionMode ConnectMode(void) const =0
Get the bitmask for the connection mode (BCP, secure login, ...)
bool SetMaxTextImageSize(size_t n)
Definition: interfaces.hpp:879
virtual CDBParams * SemiShallowClone(void) const =0
Yield a lightweight copy of these parameters, sharing representations for variable-length datatypes.
const CDBConnParams & m_Other
Definition: interfaces.hpp:357
CDBConnParams(const CDBConnParams &other)
virtual bool HasFailed(void) const =0
virtual Uint4 GetHost(void) const =0
virtual bool Send(void)=0
Send command to the server.
virtual string GetServerName(void) const =0
virtual string GetHostName(void) const =0
Get host name.
virtual bool SetMaxBlobSize(size_t nof_bytes)=0
Set maximal size for BLOB data.
virtual void SetTimeout(size_t nof_secs)=0
Set connection timeout.
virtual void PopCntxMsgHandler(CDB_UserHandler *h)=0
Remove message handler "h" and all handlers above it in the stack.
virtual ~CDBConnParams(void)
Definition: interfaces.cpp:47
virtual int RowCount(void) const =0
Get the number of rows affected by the command Special case: negative on error or if there is no way ...
virtual unsigned int GetLoginTimeout(void) const =0
Get login timeout.
const CDBConnParams * m_ChildObj
Definition: interfaces.hpp:319
virtual void PushCntxMsgHandler(CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0
Add message handler "h" to process 'context-wide' (not bound to any particular connection) error mess...
virtual size_t ItemMaxSize(unsigned int item_num) const =0
Get size (in bytes) of a result item.
virtual void CloseUnusedConnections(const string &srv_name=kEmptyStr, const string &pool_name=kEmptyStr, unsigned int max_closings=kMax_UInt)=0
Close reusable deleted connections for specified server and/or pool.
virtual string GetDriverName(void) const =0
unsigned int GetPosition(void) const
Definition: interfaces.hpp:119
virtual Uint2 GetPort(void) const =0
virtual I_ConnectionExtra & GetExtraFeatures(void)=0
Get interface for extra features that could be implemented in the driver.
virtual bool Delete(const string &table_name)=0
Delete the last fetched row.
ENameFormat GetFormat(void) const
Definition: interfaces.hpp:125
virtual const CDB_Object * GetValue(const CDBParamVariant &param) const =0
Get value of column.
virtual int GetColumnNum(void) const =0
Return number of columns in the recordset.
virtual unsigned int NofConnections(const TSvrRef &svr_ref, const string &pool_name="") const =0
virtual CDB_Connection * MakeConnection(const CDBConnParams &params)=0
Create connection object using Load Balancer / connection factory.
virtual void PopMsgHandler(CDB_UserHandler *h)=0
Remove the message handler (and all above it) from the stack.
virtual int RowCount(void) const =0
Get the number of fetched rows Special case: negative on error or if there is no way that this comman...
virtual const string & GetProcName(void) const =0
Get a name of the procedure.
virtual size_t ReadItem(void *buffer, size_t buffer_size, bool *is_null=0)=0
Read a result item body (for BLOB columns, mostly).
virtual bool Cancel(void)=0
Cancel the BCP command.
virtual bool More(const string &query_text)=0
Add more text to the language command.
virtual CDB_Object * GetItem(CDB_Object *item_buf=0, EGetItem policy=eAppendLOB)=0
Get a result item (you can use either GetItem or ReadItem).
virtual I_BlobDescriptor * GetBlobDescriptor(void)=0
Get a descriptor for a BLOB column (for SendData).
virtual const CDBParams & GetDefineParams(void) const =0
Get meta-information about rows in resultset.
CParamStmt(void)
Definition: interfaces.cpp:199
ENameFormat m_Format
Definition: interfaces.hpp:143
virtual string GetDatabaseName(void) const =0
virtual EDB_Type ItemDataType(unsigned int item_num) const =0
Get datatype of a result item.
EConnectionMode
Connection mode.
Definition: interfaces.hpp:812
EDB_ResType
EDB_ResType::
Definition: interfaces.hpp:386
virtual bool SkipItem(void)=0
Skip result item.
virtual void PopDefConnMsgHandler(CDB_UserHandler *h)=0
Remove `per-connection' mess.
virtual bool WasCanceled(void) const =0
Implementation-specific.
virtual bool CompleteBatch(void)=0
Complete batch – to store all rows transferred by far in this batch into the table.
virtual void SetHostName(const string &host_name)=0
Set host name.
virtual void SetApplicationName(const string &app_name)=0
Set application name.
virtual CRef< IConnValidator > GetConnValidator(void) const =0
CDBConnParams & operator=(const CDBConnParams &other)
virtual bool SetTimeout(unsigned int nof_secs=0)=0
Set connection timeout.
virtual const string & Password(void) const =0
Get the password.
CDBConnParamsDelegate(const CDBConnParamsDelegate &other)
void ReleaseChildObj(void) const
Definition: interfaces.hpp:298
virtual CDB_ResultProcessor * SetResultProcessor(CDB_ResultProcessor *rp)=0
Set new result-processor.
virtual void PushMsgHandler(CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0
Put the message handler into message handler stack.
virtual unsigned int GetIndex(const CDBParamVariant &param) const =0
virtual bool CompleteBCP(void)=0
Complete the BCP and store all rows transferred in last batch into the table.
virtual bool IsReusable(void) const =0
Check if this connection is a reusable one.
virtual const string & ServerName(void) const =0
Get the server name.
virtual bool UpdateBlob(unsigned int item_num, CDB_Stream &data, bool log_it=true)=0
const string m_Name
Definition: interfaces.hpp:144
conn_use_encrypt_data
Definition: interfaces.hpp:796
virtual void SetRecompile(bool recompile=true)=0
Set the "recompile before execute" flag for the stored proc Implementation-specific.
virtual string GetUserName(void) const =0
virtual const string & UserName(void) const =0
Get the user user.
virtual EDirection GetDirection(const CDBParamVariant &param) const =0
Get parameter's direction (in/out/inout).
const string & GetName(void) const
Definition: interfaces.hpp:129
virtual string GetParam(const string &key) const =0
Parameters, which are not listed above explicitly, should be retrieved via SetParam() method.
virtual CDB_SendDataCmd * SendDataCmd(unsigned int item_num, size_t size, bool log_it=true, bool discard_results=true)=0
Create send-data command.
virtual bool IsAbleTo(ECapability cpb) const =0
Check if a driver is acle to provide necessary functionality.
virtual unsigned int NofConnections(const string &srv_name="", const string &pool_name="") const =0
Return number of currently open connections in this context.
virtual EDB_ResType ResultType(void) const =0
Get type of the result.
virtual CDB_Result * Result(void)=0
Get result set.
@ eDB_CursorResult
Definition: interfaces.hpp:391
@ eDB_ParamResult
Definition: interfaces.hpp:388
@ eDB_ComputeResult
Definition: interfaces.hpp:389
@ eDB_StatusResult
Definition: interfaces.hpp:390
@ eDB_RowResult
Definition: interfaces.hpp:387
EDB_Type
Definition: types.hpp:52
#define NCBI_PARAM_DECL_EXPORT(expname, type, section, name)
Same as NCBI_PARAM_DECL but with export specifier (e.g.
Definition: ncbi_param.hpp:164
#define NCBI_DEPRECATED
uint32_t Uint4
4-byte (32-bit) unsigned integer
Definition: ncbitype.h:103
uint16_t Uint2
2-byte (16-bit) unsigned integer
Definition: ncbitype.h:101
#define kMax_UInt
Definition: ncbi_limits.h:185
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
EEncoding
Definition: ncbistr.hpp:199
#define kEmptyStr
Definition: ncbistr.hpp:123
unsigned short GetPort() const
Get the listening port number back.
enum ENcbiOwnership EOwnership
Ownership relations between objects.
yy_size_t n
Uint4 GetHost(TEndpointKey key)
mdb_mode_t mode
Definition: lmdb++.h:38
const struct ncbi::grid::netcache::search::fields::SIZE size
const struct ncbi::grid::netcache::search::fields::KEY key
static PyObject * Connect(PyObject *self, PyObject *args)
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
Help distribute connections within a pool across servers.
static Format format
Definition: njn_ioutil.cpp:53
static pcre_uint8 * buffer
Definition: pcretest.c:1051
static int buffer_size
Definition: pcretest.c:1050
static string query
#define _ASSERT
Modified on Thu May 30 12:24:42 2024 by modify_doxy.py rev. 669887