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

Go to the SVN repository for this file.

1 #ifndef DBAPI_DRIVER___PUBLIC__HPP
2 #define DBAPI_DRIVER___PUBLIC__HPP
3 
4 /* $Id: public.hpp 102711 2024-06-28 14:39:22Z 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 public interfaces
32  *
33  */
34 
37 
38 
39 // Visual Studio 2013 and 2015 overreact on deprecated methods
40 #if defined(_MSC_VER) && _MSC_VER < 1920
41  #pragma warning(push)
42  #pragma warning(disable : 4996)
43 #endif
44 
45 
46 /** @addtogroup DbPubInterfaces
47  *
48  * @{
49  */
50 
51 
53 
55 
56 
57 namespace impl
58 {
59  class CDriverContext;
60  class CConnection;
61  class CCommand;
62 }
63 
64 
65 class CAutoTrans;
66 template <class I> class CInterfaceHook;
67 
68 
70  : public I_Connection, public IBalanceable
71 {
72 public:
73  /// @brief
74  /// Check out if connection is alive.
75  ///
76  /// This function doesn't ping the server,
77  /// it just checks the status of connection which was set by the last
78  /// i/o operation.
79  ///
80  /// @return
81  /// - true if connection is alive
82  /// - false in other case.
83  virtual bool IsAlive();
84 
85  // These methods: LangCmd(), RPC(), BCPIn(), Cursor() and SendDataCmd()
86  // create and return a "command" object, register it for later use with
87  // this (and only this!) connection.
88  // On error, an exception will be thrown (they never return NULL!).
89  // It is the user's responsibility to delete the returned "command" object.
90 
91  /// Make language command
92  virtual CDB_LangCmd* LangCmd(const string& lang_query);
93  /// Make remote procedure call command
94  virtual CDB_RPCCmd* RPC(const string& rpc_name);
95  /// Make "bulk copy in" command
96  virtual CDB_BCPInCmd* BCPIn(const string& table_name);
97  /// Make cursor command
98  virtual CDB_CursorCmd* Cursor(const string& cursor_name,
99  const string& query,
100  unsigned int batch_size);
101  CDB_CursorCmd* Cursor(const string& cursor_name,
102  const string& query)
103  {
104  return Cursor(cursor_name, query, 1);
105  }
106 
107  /// Make "send-data" command
108  /// @brief
109  /// Create send-data command.
110  ///
111  /// @param desc
112  /// Lob descriptor.
113  /// @param data_size
114  /// Maximal data size.
115  /// @param log_it
116  /// Log LOB operation if this value is set to true.
117  /// @param discard_results
118  /// Discard all resultsets that might be returned from server
119  /// if this value is set to true.
120  ///
121  /// @return
122  /// Newly created send-data object.
123  ///
124  /// @sa SendData
126  size_t data_size,
127  bool log_it = true,
128  bool discard_results = true);
129 
130  /// @brief
131  /// Shortcut to send text and image to the server without using the
132  /// "Send-data" command (SendDataCmd)
133  ///
134  /// @param desc
135  /// Lob descriptor.
136  /// @param lob
137  /// Large object -- [N]TEXT, IMAGE, [N]VARCHAR(MAX), or VARBINARY(MAX).
138  /// @param log_it
139  /// Log LOB operation if this value is set to true.
140  ///
141  /// @return
142  /// - true on success.
143  ///
144  /// @sa
145  /// SendDataCmd
146  virtual bool SendData(I_BlobDescriptor& desc, CDB_Stream& lob,
147  bool log_it = true);
148 
149  /// @brief
150  /// Set database name
151  ///
152  /// @param name
153  /// Database name
154  void SetDatabaseName(const string& name);
155 
156  /// @brief
157  /// Reset the connection to the "ready" state (cancel all active commands)
158  ///
159  /// @return
160  /// - true on success.
161  virtual bool Refresh();
162 
163  /// @brief
164  /// Get the server name.
165  ///
166  /// @return
167  /// Server/Service name.
168  virtual const string& ServerName() const;
169 
170  /// @brief
171  /// Get the host.
172  ///
173  /// @return
174  /// host ip.
175  virtual Uint4 Host() const;
176 
177  /// @brief
178  /// Get the port.
179  ///
180  /// @return
181  /// port.
182  virtual Uint2 Port() const;
183 
184  /// @brief
185  /// Get the user user.
186  ///
187  /// @return
188  /// User name.
189  virtual const string& UserName() const;
190 
191  /// @brief
192  /// Get the password.
193  ///
194  /// @return
195  /// Password value.
196  virtual const string& Password() const;
197 
198  /// @brief
199  /// Get the database name.
200  ///
201  /// @return
202  /// Database name.
203  virtual const string& DatabaseName(void) const;
204 
205  /// @brief
206  /// Get the bitmask for the connection mode (BCP, secure login, ...)
207  ///
208  /// @return
209  /// bitmask for the connection mode (BCP, secure login, ...)
211 
212  /// @brief
213  /// Check if this connection is a reusable one
214  ///
215  /// @return
216  /// - true if this connection is a reusable one.
217  virtual bool IsReusable() const;
218 
219  /// Indicate how many times (if at all) this connection has been
220  /// previously used.
221  unsigned int GetReuseCount() const;
222 
223  /// @brief
224  /// Find out which connection pool this connection belongs to
225  ///
226  /// @return
227  /// connection pool
228  virtual const string& PoolName() const;
229 
230  /// @brief
231  /// Get pointer to the driver context
232  ///
233  /// @return
234  /// pointer to the driver context
235  virtual I_DriverContext* Context() const;
236 
237  /// @brief
238  /// Put the message handler into message handler stack
239  ///
240  /// @param h
241  /// Error message handler.
242  /// @param ownership
243  /// If set to eNoOwnership, it is user's responsibility to unregister
244  /// and delete the error message handler.
245  /// If set to eTakeOwnership, then DBAPI will take ownership of the
246  /// error message handler and delete it itself.
247  ///
248  /// @sa
249  /// PopMsgHandler
250  virtual void PushMsgHandler(CDB_UserHandler* h,
251  EOwnership ownership = eNoOwnership);
252 
253  /// @brief
254  /// Remove the message handler (and all above it) from the stack
255  ///
256  /// @param h
257  /// Error message handler.
258  /// @sa
259  /// PushMsgHandler
260  virtual void PopMsgHandler(CDB_UserHandler* h);
261 
262  /// @brief
263  /// Set new result-processor.
264  ///
265  /// @param rp
266  /// New result-processor.
267  ///
268  /// @return
269  /// Old result-processor
271 
272  /// Destructor
273  virtual ~CDB_Connection();
274 
275  /// Abort the connection
276  ///
277  /// @return
278  /// TRUE - if succeeded, FALSE if not
279  ///
280  /// @note
281  /// Attention: it is not recommended to use this method unless you
282  /// absolutely have to. The expected implementation is - close
283  /// underlying file descriptor[s] without destroing any objects
284  /// associated with a connection.
285  ///
286  /// @sa
287  /// Close
288  virtual bool Abort();
289 
290  /// Close an open connection.
291  /// This method will return connection (if it is created as reusable) to
292  /// its connection pool
293  ///
294  /// @return
295  /// TRUE - if succeeded, FALSE if not
296  ///
297  /// @sa
298  /// Abort, I_DriverContext::Connect
299  virtual bool Close(void);
300 
301  /// @brief
302  /// Set connection timeout.
303  ///
304  /// This timeout limits how long each query or the like can take.
305  /// @param nof_secs
306  /// Number of seconds. If "nof_secs" is zero or is "too big"
307  /// (depends on the underlying DB API), then set the timeout to infinite.
308  /// @sa GetTimeout, SetCancelTimeout, I_DriverContext::SetTimeout, I_DriverContext::SetLoginTimeout
309  virtual void SetTimeout(size_t nof_secs);
310 
311  /// Set timeout for command cancellation and connection closing
312  ///
313  /// This timeout limits how long to wait for the server to acknowledge
314  /// requests to cancel a query gracefully or close a connection gracefully
315  /// before pulling the plug.
316  /// @sa GetCancelTimeout, SetTimeout, I_DriverContext::SetTimeout, I_DriverContext::SetLoginTimeout
317  virtual void SetCancelTimeout(size_t nof_secs);
318 
319  /// Get connection timeout.
320  ///
321  /// This timeout limits how long each query or the like can take.
322  /// @sa SetTimeout, GetCancelTimeout, I_DriverContext::GetTimeout, I_DriverContext::GetLoginTimeout
323  size_t GetTimeout(void) const;
324 
325  /// Get timeout for command cancellation and connection closing
326  ///
327  /// This timeout limits how long to wait for the server to acknowledge
328  /// requests to cancel a query gracefully or close a connection gracefully
329  /// before pulling the plug.
330  /// @sa SetCancelTimeout, GetTimeout, I_DriverContext::GetTimeout, I_DriverContext::GetLoginTimeout
331  size_t GetCancelTimeout(void) const;
332 
333  /// Get interface for extra features that could be implemented in the driver.
334  virtual I_ConnectionExtra& GetExtraFeatures(void);
335 
336  virtual string GetDriverName(void) const;
337 
338  virtual string GetVersionString(void) const;
339 
340  bool HasTransaction(void) const
341  {
342  return m_HasTransaction;
343  }
344 
345 public:
346  // Deprecated legacy methods.
347  // CXX-601
348 
349  /// @deprecated
350 #ifndef NCBI_UNDEPRECATE__DBAPI_OLD_CONNECTION
352 #endif
353  CDB_LangCmd* LangCmd(const string& lang_query, unsigned int /*unused*/)
354  {
355  return LangCmd(lang_query);
356  }
357  /// @deprecated
358 #ifndef NCBI_UNDEPRECATE__DBAPI_OLD_CONNECTION
360 #endif
361  CDB_RPCCmd* RPC(const string& rpc_name, unsigned int /*unused*/)
362  {
363  return RPC(rpc_name);
364  }
365  /// @deprecated
366 #ifndef NCBI_UNDEPRECATE__DBAPI_OLD_CONNECTION
368 #endif
369  CDB_BCPInCmd* BCPIn(const string& table_name, unsigned int /*unused*/)
370  {
371  return BCPIn(table_name);
372  }
373  /// @deprecated
374 #ifndef NCBI_UNDEPRECATE__DBAPI_OLD_CONNECTION
376 #endif
377  CDB_CursorCmd* Cursor(const string& cursor_name,
378  const string& query,
379  unsigned int /*unused*/,
380  unsigned int batch_size)
381  {
382  return Cursor(cursor_name, query, batch_size);
383  }
384 
385  void FinishOpening(void);
386 
387 private:
390 
392 
393  // Prohibit default- and copy- constructors, and assignment
395  CDB_Connection& operator= (const CDB_Connection&);
397 
398  void ReleaseImpl(void)
399  {
400  m_ConnImpl = NULL;;
401  }
402 
403  bool x_IsAlive(void);
404 
405  // The constructor should be called by "I_DriverContext" only!
406  friend class impl::CDriverContext;
407  friend class CAutoTrans;
408  friend class CInterfaceHook<CDB_Connection>;
409 };
410 
411 
413 {
414 public:
415  /// @brief
416  /// Get type of the result
417  ///
418  /// @return
419  /// Result type
420  virtual EDB_ResType ResultType() const;
421 
422  /// Get meta-information about rows in resultset.
423  virtual const CDBParams& GetDefineParams(void) const;
424 
425  /// Get # of items (columns) in the result
426  /// @brief
427  /// Get # of items (columns) in the result.
428  ///
429  /// @return
430  /// Number of items (columns) in the result.
431  virtual unsigned int NofItems() const;
432 
433  /// @brief
434  /// Get name of a result item.
435  ///
436  /// @param item_num
437  /// Number of item, starting from 0.
438  ///
439  /// @return
440  /// NULL if "item_num" >= NofItems(), otherwise item name.
441  virtual const char* ItemName(unsigned int item_num) const;
442 
443  /// @brief
444  /// Get size (in bytes) of a result item.
445  ///
446  /// @param item_num
447  /// Number of item, starting from 0.
448  ///
449  /// @return
450  /// Return zero if "item_num" >= NofItems().
451  virtual size_t ItemMaxSize(unsigned int item_num) const;
452 
453  /// @brief
454  /// Get datatype of a result item.
455  ///
456  /// @param item_num
457  /// Number of item, starting from 0.
458  ///
459  /// @return
460  /// Return 'eDB_UnsupportedType' if "item_num" >= NofItems().
461  virtual EDB_Type ItemDataType(unsigned int item_num) const;
462 
463  /// @brief
464  /// Fetch next row
465  ///
466  /// @return
467  /// - true if a record was fetched.
468  /// - false if no more record can be fetched.
469  virtual bool Fetch();
470 
471  /// @brief
472  /// Return current item number we can retrieve (0,1,...)
473  ///
474  /// @return
475  /// Return current item number we can retrieve (0,1,...)
476  /// Return "-1" if no more items left (or available) to read.
477  virtual int CurrentItemNo() const;
478 
479  /// @brief
480  /// Return number of columns in the recordset.
481  ///
482  /// @return
483  /// number of columns in the recordset.
484  virtual int GetColumnNum(void) const;
485 
486  /// @brief
487  /// Get a result item (you can use either GetItem or ReadItem).
488  ///
489  /// @param item_buf
490  /// If "item_buf" is not NULL, then use "*item_buf" (its type should be
491  /// compatible with the type of retrieved item!) to retrieve the item to;
492  /// otherwise allocate new "CDB_Object".
493  /// If the existing "item_buf" has a BLOB type (CDB_Image, CDB_Text,
494  /// CDB_VarBinaryMax, or CDB_VarCharMax), the value will be *appended*
495  /// to the "item_buf" by default (policy == eAppendLOB).
496  ///
497  /// @param policy
498  /// Data retrieval policy. If policy == eAppendLOB *and* "item_buf" has a
499  /// BLOB type (CDB_Image, CDB_Text, CDB_VarBinaryMax, or CDB_VarCharMax),
500  /// data will be *appended* to the end of previously assigned data.
501  /// Otherwise (policy == eAssignLOB or "item_buf" has some other type),
502  /// the new value will be *assigned* to the "item_buf" object.
503  ///
504  /// @return
505  /// a result item
506  ///
507  /// @sa
508  /// ReadItem, SkipItem
509  virtual CDB_Object* GetItem(CDB_Object* item_buf = 0, EGetItem policy = eAppendLOB);
510 
511  /// @brief
512  /// Read a result item body (for BLOB columns, mostly).
513  /// Throw an exception on any error.
514  ///
515  /// @param buffer
516  /// Buffer to fill with data.
517  /// @param buffer_size
518  /// Buffere size.
519  /// @param is_null
520  /// Set "*is_null" to TRUE if the item is <NULL>.
521  ///
522  /// @return
523  /// number of successfully read bytes.
524  ///
525  /// @sa
526  /// GetItem, SkipItem
527  virtual size_t ReadItem(void* buffer, size_t buffer_size,
528  bool* is_null = 0);
529 
530  /// @brief
531  /// Get a descriptor for a BLOB column (for SendData).
532  ///
533  /// @return
534  /// Return NULL if this result doesn't (or can't) have a BLOB descriptor.
535  ///
536  /// @note
537  /// You need to call ReadItem (maybe even with buffer_size == 0)
538  /// before calling this method!
539  /// @deprecated
540  /// Please use CDB_BlobDescriptor instead.
541  /// @sa
542  /// CDB_BlobDescriptor
544  virtual I_BlobDescriptor* GetBlobDescriptor();
545 
546  /// @brief
547  /// Skip result item
548  ///
549  /// @return
550  /// TRUE on success.
551  ///
552  /// @sa
553  /// GetItem, ReadItem
554  virtual bool SkipItem();
555 
556  /// Destructor
557  virtual ~CDB_Result();
558 
559 private:
561  {
562  return m_ResImpl;
563  }
565  {
566  _ASSERT(m_ResImpl);
567  return *m_ResImpl;
568  }
569 
570  void ReleaseImpl(void)
571  {
572  m_ResImpl = NULL;;
573  }
574 
575 private:
577 
579 
580  // Prohibit default- and copy- constructors, and assignment
581  CDB_Result& operator= (const CDB_Result&);
583  CDB_Result(void);
584 
585  // The constructor should be called by "I_***Cmd" only!
586  friend class impl::CConnection;
587  friend class impl::CCommand;
588  friend class CInterfaceHook<CDB_Result>;
589 };
590 
591 
592 
594 {
595 public:
596  /// Add more text to the language command
597  /// @deprecated
598  // CXX-601
599 #ifndef NCBI_UNDEPRECATE__DBAPI_OLD_LANGCMD
601 #endif
602  virtual bool More(const string& query_text);
603 
604  /// Get meta-information about parameters.
605  virtual CDBParams& GetBindParams(void);
606  virtual CDBParams& GetDefineParams(void);
607 
608  // Bind cmd parameter with name "name" to the object pointed by "value"
609  bool BindParam(const string& name, CDB_Object* value)
610  {
611  GetBindParams().Bind(name, value);
612  return true;
613  }
614 
615  // Set cmd parameter with name "name" to the object pointed by "value"
616  bool SetParam(const string& name, CDB_Object* value)
617  {
618  GetBindParams().Set(name, value);
619  return true;
620  }
621 
622  /// Send command to the server
623  virtual bool Send();
624  /// Implementation-specific.
625  /// @deprecated
626  NCBI_DEPRECATED virtual bool WasSent() const;
627 
628  /// Cancel the command execution
629  virtual bool Cancel();
630  /// Implementation-specific.
631  /// @deprecated
632  NCBI_DEPRECATED virtual bool WasCanceled() const;
633 
634  /// Get result set
635  virtual CDB_Result* Result();
636  virtual bool HasMoreResults() const;
637 
638  /// Check if command has failed
639  virtual bool HasFailed() const;
640 
641  /// Get the number of rows affected by the command.
642  /// Special case: negative on error or if there is no way that this
643  /// command could ever affect any rows (like PRINT).
644  virtual int RowCount() const;
645 
646  /// Dump the results of the command
647  /// If result processor is installed for this connection, then it will be
648  /// called for each result set
649  virtual void DumpResults();
650 
651  // Destructor
652  virtual ~CDB_LangCmd();
653 
654 private:
656 
658 
659  // Prohibit default- and copy- constructors, and assignment
660  CDB_LangCmd& operator= (const CDB_LangCmd&);
663 
664  void ReleaseImpl(void)
665  {
666  m_CmdImpl = NULL;;
667  }
668 
669  // The constructor should be called by "I_Connection" only!
670  friend class impl::CConnection;
671  friend class CInterfaceHook<CDB_LangCmd>;
672 };
673 
674 
675 
677 {
678 public:
679  /// Get meta-information about parameters.
680  virtual CDBParams& GetBindParams(void);
681  virtual CDBParams& GetDefineParams(void);
682 
683  // Binding
684  bool BindParam(
685  const string& name,
686  CDB_Object* value,
687  bool out_param = false
688  )
689  {
690  GetBindParams().Bind(name, value, out_param);
691  return true;
692  }
693 
694  // Setting
695  bool SetParam(
696  const string& name,
697  CDB_Object* value,
698  bool out_param = false
699  )
700  {
701  GetBindParams().Set(name, value, out_param);
702  return true;
703  }
704 
705  /// Send command to the server
706  virtual bool Send();
707  /// Implementation-specific.
708  /// @deprecated
709  NCBI_DEPRECATED virtual bool WasSent() const;
710 
711  /// Cancel the command execution
712  virtual bool Cancel();
713  /// Implementation-specific.
714  /// @deprecated
715  NCBI_DEPRECATED virtual bool WasCanceled() const;
716 
717  /// Get result set.
718  /// Return NULL if no more results left to read.
719  /// Throw exception on error or if attempted to read after NULL was returned
720  virtual CDB_Result* Result();
721 
722  /// Return TRUE if it makes sense (at all) to call Result()
723  virtual bool HasMoreResults() const;
724 
725  /// Check if command has failed
726  virtual bool HasFailed() const;
727 
728  /// Get the number of rows affected by the command
729  /// Special case: negative on error or if there is no way that this
730  /// command could ever affect any rows (like PRINT).
731  virtual int RowCount() const;
732 
733  /// Dump the results of the command
734  /// If result processor is installed for this connection, then it will be
735  /// called for each result set
736  virtual void DumpResults();
737 
738  /// Set the "recompile before execute" flag for the stored proc
739  /// Implementation-specific.
740  /// @deprecated
741  NCBI_DEPRECATED virtual void SetRecompile(bool recompile = true);
742 
743  /// Get a name of the procedure.
744  virtual const string& GetProcName(void) const;
745 
746  // Destructor
747  virtual ~CDB_RPCCmd();
748 
749 private:
751 
753 
754  // Prohibit default- and copy- constructors, and assignment
755  CDB_RPCCmd& operator= (const CDB_RPCCmd&);
758 
759  void ReleaseImpl(void)
760  {
761  m_CmdImpl = NULL;;
762  }
763 
764  // Constructor should be called by "I_Connection" only!
765  friend class impl::CConnection;
766  friend class CInterfaceHook<CDB_RPCCmd>;
767 };
768 
769 
770 
772 {
773 public:
774  /// Set hints by one call. Resets everything that was set by Add*Hint().
775  void SetHints(CTempString hints);
776 
777  /// Type of hint that can be set.
778  enum EBCP_Hints {
784  eFireTriggers
785  };
786 
787  /// Add hint with value.
788  /// Can be used with any hint type except eOrder and with e..PerBatch
789  /// value should be non-zero.
790  /// Resets everything that was set by SetHints().
791  void AddHint(EBCP_Hints hint, unsigned int value = 0);
792 
793  /// Add "ORDER" hint.
794  /// Resets everything that was set by SetHints().
795  void AddOrderHint(CTempString columns);
796 
797  /// Get meta-information about parameters.
798  virtual CDBParams& GetBindParams(void);
799 
800  // Binding
801  bool Bind(unsigned int column_num, CDB_Object* value);
802 
803  /// Send row to the server
804  virtual bool SendRow();
805 
806  /// Complete batch -- to store all rows transferred by far in this batch
807  /// into the table
808  virtual bool CompleteBatch();
809 
810  /// Cancel the BCP command
811  virtual bool Cancel();
812 
813  /// Complete the BCP and store all rows transferred in last batch into
814  /// the table
815  virtual bool CompleteBCP();
816 
817  // Destructor
818  virtual ~CDB_BCPInCmd();
819 
820 private:
822 
824 
825  // Prohibit default- and copy- constructors, and assignment
826  CDB_BCPInCmd& operator= (const CDB_BCPInCmd&);
829 
830  void ReleaseImpl(void)
831  {
832  m_CmdImpl = NULL;;
833  }
834 
835  // The constructor should be called by "I_Connection" only!
836  friend class impl::CConnection;
837  friend class CInterfaceHook<CDB_BCPInCmd>;
838 };
839 
840 
841 
843 {
844 public:
845  /// Get meta-information about parameters.
846  virtual CDBParams& GetBindParams(void);
847  virtual CDBParams& GetDefineParams(void);
848 
849  // Binding
850  bool BindParam(const string& name, CDB_Object* value)
851  {
852  GetBindParams().Bind(name, value);
853  return true;
854  }
855 
856  /// Open the cursor.
857  /// Return NULL if cursor resulted in no data.
858  /// Throw exception on error.
859  virtual CDB_Result* Open();
860 
861  /// Update the last fetched row.
862  /// NOTE: the cursor must be declared for update in CDB_Connection::Cursor()
863  virtual bool Update(const string& table_name, const string& upd_query);
864 
865  /// @deprecated
866  /// Please use CDB_Connection::SendData instead.
867  /// @sa
868  /// CDB_Connection::SendData
870  virtual bool UpdateBlob(unsigned int item_num, CDB_Stream& data,
871  bool log_it = true);
872  /// Make "send-data" command
873  /// @brief
874  /// Create send-data command.
875  ///
876  /// @param item_num
877  /// Column number to rewrite.
878  /// @param size
879  /// Maximal data size.
880  /// @param log_it
881  /// Log LOB operation if this value is set to true.
882  /// @param discard_results
883  /// Discard all resultsets that might be returned from server
884  /// if this value is set to true.
885  ///
886  /// @return
887  /// Newly created send-data object.
888  /// @deprecated
889  /// Please use CDB_Connection::SendDataCmd instead.
890  /// @sa
891  /// CDB_Connection::SendDataCmd
893  virtual CDB_SendDataCmd* SendDataCmd(unsigned int item_num, size_t size,
894  bool log_it = true,
895  bool discard_results = true);
896 
897  /// Delete the last fetched row.
898  /// NOTE: the cursor must be declared for delete in CDB_Connection::Cursor()
899  virtual bool Delete(const string& table_name);
900 
901  /// Get the number of fetched rows
902  /// Special case: negative on error or if there is no way that this
903  /// command could ever affect any rows (like PRINT).
904  virtual int RowCount() const;
905 
906  /// Close the cursor.
907  /// Return FALSE if the cursor is closed already (or not opened yet)
908  virtual bool Close();
909 
910  // Destructor
911  virtual ~CDB_CursorCmd();
912 
913 private:
915 
917 
918  // Prohibit default- and copy- constructors, and assignment
919  CDB_CursorCmd& operator= (const CDB_CursorCmd&);
922 
923  void ReleaseImpl(void)
924  {
925  m_CmdImpl = NULL;;
926  }
927 
928  // The constructor should be called by "I_Connection" only!
929  friend class impl::CConnection;
930  friend class CInterfaceHook<CDB_CursorCmd>;
931 };
932 
933 
934 
936 {
937 public:
938  /// Send chunk of data to the server.
939  /// Return number of bytes actually transferred to server.
940  virtual size_t SendChunk(const void* data, size_t size);
941  virtual bool Cancel(void);
942 
943  /// Get result set
944  virtual CDB_Result* Result();
945  virtual bool HasMoreResults() const;
946 
947  /// Dump the results of the command
948  /// If result processor is installed for this connection, then it will be
949  /// called for each result set
950  virtual void DumpResults();
951 
952  // Destructor
953  virtual ~CDB_SendDataCmd();
954 
955 private:
957 
959 
960  // Prohibit default- and copy- constructors, and assignment
961  CDB_SendDataCmd& operator= (const CDB_SendDataCmd&);
964 
965  void ReleaseImpl(void)
966  {
967  m_CmdImpl = NULL;;
968  }
969 
970  // The constructor should be called by "I_Connection" only!
971  friend class impl::CConnection;
972  friend class CInterfaceHook<CDB_SendDataCmd>;
973 };
974 
975 
976 
978 {
979 public:
980  enum ETDescriptorType {eUnknown, eText, eBinary};
981 
982  CDB_BlobDescriptor(const string& table_name,
983  const string& column_name,
984  const string& search_conditions,
985  ETDescriptorType column_type = eUnknown,
986  ETriState has_legacy_type = eTriState_Unknown);
987  virtual ~CDB_BlobDescriptor(void);
988 
989  virtual int DescriptorType(void) const;
990 
991  const string& TableName() const { return m_TableName; }
992  void SetTableName(const string& name) { m_TableName = name; }
993  const string& ColumnName() const { return m_ColumnName; }
994  void SetColumnName(const string& name) { m_ColumnName = name; }
995  const string& SearchConditions() const { return m_SearchConditions; }
996  void SetSearchConditions(const string& cond) { m_SearchConditions = cond; }
997 
999  {
1000  return m_ColumnType;
1001  }
1003  {
1004  m_ColumnType = type;
1005  }
1006 
1008  return m_HasLegacyType;
1009  }
1011  m_HasLegacyType = state;
1012  }
1013 
1014 protected:
1015  string m_TableName;
1020 };
1021 
1022 // historical name
1024 
1025 
1027 {
1028 public:
1030  virtual ~CDB_ResultProcessor();
1031 
1032  /// The default implementation just dumps all rows.
1033  /// To get the data you will need to override this method.
1034  virtual void ProcessResult(CDB_Result& res);
1035 
1036 private:
1037  // Prohibit default- and copy- constructors, and assignment
1041 
1042  void ReleaseConn(void);
1043  void SetConn(CDB_Connection* c);
1044 
1048 
1049  friend class impl::CConnection;
1050 };
1051 
1052 
1053 ////////////////////////////////////////////////////////////////////////////////
1055 {
1056 public:
1057  /// Helper class to allow safe initialization from higher-layer objects.
1058  class CSubject {
1059  public:
1060  CSubject(CDB_Connection& connection) : m_Connection(connection) { }
1061 
1062  private:
1064  friend class CAutoTrans;
1065  };
1066 
1067  CAutoTrans(const CSubject& subject);
1068  ~CAutoTrans(void);
1069 
1070 public:
1071  bool Continue(void) const
1072  {
1073  return m_Abort;
1074  }
1075  void Finish(void)
1076  {
1077  m_Abort = false;
1078  }
1079 
1080 private:
1083 
1084  void BeginTransaction(void);
1085  void Commit(void);
1086  void Rollback(void);
1087  int GetTranCount(void);
1088 
1089 private:
1090  bool m_Abort;
1094 };
1095 
1096 
1097 ////////////////////////////////////////////////////////////////////////////////
1098 inline
1100 {
1101  return CAutoTrans::CSubject(connection);
1102 }
1103 
1104 
1105 ////////////////////////////////////////////////////////////////////////////////
1106 /// Establish an automatically managed SQL transaction on the
1107 /// specified connection for the duration of the immediately following
1108 /// code block: DBAPI_TRANSACTION(connection) { ... }
1109 ///
1110 /// Automatically COMMIT upon reaching the end of the block normally.
1111 /// Automatically ROLLBACK upon leaving the block early, via a break
1112 /// or return statement or uncaught exception. A client crash or
1113 /// severed connection will trigger an implicit server-side ROLLBACK.
1114 ///
1115 /// Nested transactions are possible, and will use savepoints for
1116 /// inner transactions so they can fail cleanly (without also
1117 /// canceling outer transactions).
1118 #define DBAPI_TRANSACTION(connection) \
1119 for(ncbi::CAutoTrans auto_trans(ncbi::DBAPI_MakeTrans(connection)); \
1120  auto_trans.Continue(); \
1121  auto_trans.Finish())
1122 
1123 
1125 
1126 
1127 /* @} */
1128 
1129 #if defined(_MSC_VER) && _MSC_VER < 1920
1130  #pragma warning(pop)
1131 #endif
1132 
1133 
1134 #endif /* DBAPI_DRIVER___PUBLIC__HPP */
Helper class to allow safe initialization from higher-layer objects.
Definition: public.hpp:1058
CDBParams.
Definition: interfaces.hpp:154
CTempString implements a light-weight string on top of a storage buffer whose lifetime management is ...
Definition: tempstr.hpp:65
virtual const string & ServerName(void) const =0
virtual Uint4 Host(void) const =0
virtual Uint2 Port(void) const =0
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 CS_COMMAND * cmd
Definition: ct_dynamic.c:26
static const char table_name[]
Definition: bcp.c:249
static int type
Definition: getdata.c:31
static const column_t columns[]
Definition: utf8_2.c:22
char data[12]
Definition: iconv.c:80
ETriState
Enumeration to represent a tristate value.
Definition: ncbimisc.hpp:128
@ eTriState_Unknown
The value is indeterminate.
Definition: ncbimisc.hpp:129
@ eNoOwnership
No ownership is assumed.
Definition: ncbi_types.h:135
#define NULL
Definition: ncbistd.hpp:225
virtual bool IsAlive(void)=0
Check out if connection is alive.
virtual const string & PoolName(void) const =0
Find out which connection pool this connection belongs to.
virtual CDBParams & Set(const CDBParamVariant &param, CDB_Object *value, bool out_param=false)
This method stores copy of data.
Definition: interfaces.cpp:161
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 CDB_CursorCmd * Cursor(const string &cursor_name, const string &query, unsigned int batch_size)=0
Cursor.
virtual CDB_RPCCmd * RPC(const string &rpc_name)=0
Remote procedure call.
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)
virtual CDB_BCPInCmd * BCPIn(const string &table_name)=0
"Bulk copy in" command
virtual const string & DatabaseName(void) const =0
Get the database name.
virtual bool Close(void)=0
Close an open connection.
virtual size_t GetTimeout(void) const =0
Get connection timeout.
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 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, ...)
virtual string GetVersionString(void) const
Driver version, supplied here rather than by the context for ODBC's sake.
Definition: interfaces.cpp:357
virtual void SetTimeout(size_t nof_secs)=0
Set connection timeout.
virtual CDBParams & Bind(const CDBParamVariant &param, CDB_Object *value, bool out_param=false)
This method stores pointer to data.
Definition: interfaces.cpp:150
virtual I_ConnectionExtra & GetExtraFeatures(void)=0
Get interface for extra features that could be implemented in the driver.
virtual void PopMsgHandler(CDB_UserHandler *h)=0
Remove the message handler (and all above it) from the stack.
EDB_ResType
EDB_ResType::
Definition: interfaces.hpp:386
virtual const string & Password(void) const =0
Get the password.
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 bool IsReusable(void) const =0
Check if this connection is a reusable one.
virtual const string & UserName(void) const =0
Get the user user.
impl::CResult * GetIResultPtr(void) const
Definition: public.hpp:560
CDB_LangCmd * LangCmd(const string &lang_query, unsigned int)
Definition: public.hpp:353
CDB_Connection & m_Conn
Definition: public.hpp:1091
CAutoTrans(const CSubject &subject)
Definition: public.cpp:1266
bool SetParam(const string &name, CDB_Object *value, bool out_param=false)
Definition: public.hpp:695
const string & SearchConditions() const
Definition: public.hpp:995
void SetHasLegacyType(ETriState state)
Definition: public.hpp:1010
void ReleaseImpl(void)
Definition: public.hpp:398
bool SetParam(const string &name, CDB_Object *value)
Definition: public.hpp:616
string m_SavepointName
Definition: public.hpp:1093
CAutoTrans & operator=(const CAutoTrans &)
void SetTableName(const string &name)
Definition: public.hpp:992
ETriState m_HasLegacyType
Definition: public.hpp:1019
impl::CConnection * m_ConnImpl
Definition: public.hpp:388
NCBI_DECLARE_INTERFACE_VERSION(I_DriverContext, "xdbapi", 14, 0, 0)
impl::CResult * m_ResImpl
Definition: public.hpp:576
CDB_CursorCmd * Cursor(const string &cursor_name, const string &query, unsigned int, unsigned int batch_size)
Definition: public.hpp:377
impl::CResult & GetIResult(void) const
Definition: public.hpp:564
impl::CSendDataCmd * m_CmdImpl
Definition: public.hpp:956
impl::CBaseCmd * m_CmdImpl
Definition: public.hpp:821
CAutoTrans(const CAutoTrans &)
bool BindParam(const string &name, CDB_Object *value)
Definition: public.hpp:609
ETDescriptorType m_ColumnType
Definition: public.hpp:1018
CDB_ResultProcessor(const CDB_ResultProcessor &)
bool m_Abort
Definition: public.hpp:1090
CDB_CursorCmd * Cursor(const string &cursor_name, const string &query)
Definition: public.hpp:101
string m_SearchConditions
Definition: public.hpp:1017
CSubject(CDB_Connection &connection)
Definition: public.hpp:1060
CDB_Result(const CDB_Result &)
bool m_HasTransaction
Definition: public.hpp:389
CDB_ResultProcessor * m_Next
Definition: public.hpp:1047
CDB_ResultProcessor * m_Prev
Definition: public.hpp:1046
impl::CBaseCmd * m_CmdImpl
Definition: public.hpp:655
void ReleaseImpl(void)
Definition: public.hpp:570
CDB_BlobDescriptor CDB_ITDescriptor
Definition: public.hpp:1023
~CAutoTrans(void)
Definition: public.cpp:1284
impl::CBaseCmd * m_CmdImpl
Definition: public.hpp:750
CAutoTrans::CSubject DBAPI_MakeTrans(CDB_Connection &connection)
Definition: public.hpp:1099
CDB_RPCCmd(const CDB_RPCCmd &)
void Commit(void)
Definition: public.cpp:1323
CDB_BCPInCmd * BCPIn(const string &table_name, unsigned int)
Definition: public.hpp:369
bool Continue(void) const
Definition: public.hpp:1071
CDB_LangCmd(const CDB_LangCmd &)
ETriState GetHasLegacyType(void) const
Definition: public.hpp:1007
void ReleaseImpl(void)
Definition: public.hpp:830
CDB_BCPInCmd(const CDB_BCPInCmd &)
CDB_Connection(const CDB_Connection &)
ETDescriptorType GetColumnType(void) const
Definition: public.hpp:998
void ReleaseImpl(void)
Definition: public.hpp:923
void SetColumnName(const string &name)
Definition: public.hpp:994
void ReleaseImpl(void)
Definition: public.hpp:759
CDB_Connection & m_Connection
Definition: public.hpp:1063
EBCP_Hints
Type of hint that can be set.
Definition: public.hpp:778
void ReleaseImpl(void)
Definition: public.hpp:664
CDB_RPCCmd * RPC(const string &rpc_name, unsigned int)
Definition: public.hpp:361
void Rollback(void)
Definition: public.cpp:1332
void SetSearchConditions(const string &cond)
Definition: public.hpp:996
CDB_SendDataCmd(const CDB_CursorCmd &)
impl::CBaseCmd * m_CmdImpl
Definition: public.hpp:914
int m_TranCount
Definition: public.hpp:1092
void ReleaseImpl(void)
Definition: public.hpp:965
void Finish(void)
Definition: public.hpp:1075
void BeginTransaction(void)
Definition: public.cpp:1313
int GetTranCount(void)
Definition: public.cpp:1349
bool BindParam(const string &name, CDB_Object *value, bool out_param=false)
Definition: public.hpp:684
CDB_Result(void)
const string & ColumnName() const
Definition: public.hpp:993
CDB_CursorCmd(const CDB_CursorCmd &)
bool HasTransaction(void) const
Definition: public.hpp:340
void SetColumnType(ETDescriptorType type)
Definition: public.hpp:1002
CDB_Connection * m_Con
Definition: public.hpp:1045
bool BindParam(const string &name, CDB_Object *value)
Definition: public.hpp:850
const string & TableName() const
Definition: public.hpp:991
@ eCheckConstraints
Definition: public.hpp:783
@ eKilobytesPerBatch
Definition: public.hpp:781
EDB_Type
Definition: types.hpp:52
NCBI_XNCBI_EXPORT void Abort(void)
Smart abort function.
Definition: ncbidiag.cpp:8150
#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 END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
enum ENcbiOwnership EOwnership
Ownership relations between objects.
#define NCBI_DBAPIDRIVER_EXPORT
Definition: ncbi_export.h:392
@ eText
Definition: map_control.hpp:50
const struct ncbi::grid::netcache::search::fields::SIZE size
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
double r(size_t dimension_, const Int4 *score_, const double *prob_, double theta_)
static uint8_t * buffer
Definition: pcre2test.c:1016
Plugin manager (using class factory paradigm).
static string subject
static string query
Definition: type.c:6
#define _ASSERT
Modified on Fri Sep 20 14:58:25 2024 by modify_doxy.py rev. 669887