Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).

Reference for Utility Classes

This chapter describes some useful classes that do not correspond to Caché datatypes and are not automatically inherited by proxies.

Data Processing Classes

  • Transaction — provides automatic rollback if the program encounters an exception.

  • LC_Batch — batch insert class for the Light C++ Binding.

  • d_query — provides methods for preparing an SQL query, binding parameters, executing the query, and traversing the result set.

Class InterSystems::Transaction

This class provides a guaranteed automatic rollback in case of exceptions. When a Transaction object goes out of scope, the transaction is rolled back if neither commit() nor rollback() has been called. Unlike the Database transaction methods, this class does not allow nested transactions. For more information about both types of transaction, see Using Transactions.

Constructor

Transaction()

Class constructor starts the transaction (unlike a Database object, which requires a call to Database::tstart()).

   InterSystems::Transaction::Transaction
   (  Database * _db ) [inline]

Member list

commit()

commits the transaction.

   void InterSystems::Transaction::commit
   ( ) [inline]

Calling commit() more than once for the same Transaction object does nothing (unlike Database::tcommit(), which can be called repeatedly to roll back multiple levels of a nested transaction).

rollback()

rolls back the current transaction.

   void InterSystems::Transaction::rollback
   ( ) [inline]

Called automatically if the Transaction object goes out of scope before the transaction is committed or rolled back.

Class InterSystems::LC_Batch

This class provides methods for batch insertion using the Light C++ Binding. For more information, see Batch Insert.

Constructor

LC_Batch()

   InterSystems::LC_Batch::LC_Batch
   (  LC_Database * _db,
      int _concurrency = 1,
      bool _return_ids = false,
      bool _throw_errs = true,
      size_t reserve_size = 32768,
      bool _do_tx = false
   ) [inline]

Member list

clear()

To avoid saving objects already added to batch, call clear()

   void InterSystems::LC_Batch::clear
   ( ) [inline]
clear_errors()

   void InterSystems::LC_Batch::clear_errors
   ( ) [inline]
clear_ids()

   void InterSystems::LC_Batch::clear_ids
   ( ) [inline]
close()

   void LC_Batch::close
   ( )
flush()

To save objects to database, call flush(), close(), or destroy the batch object

   void LC_Batch::flush
   ( )
get_errors()

Return a list of errors.

   const std::vector< std::pair<d_status, d_binary> >& 
      InterSystems::LC_Batch::get_errors
   ( ) const [inline]

After flush(), get_errors() returns list:

  • If no errors, size() of list is 0

  • If errors, each list entry is pairing of error status and object serialization

  • Projection object has set_from_err_list() member function, which can be used to examine properties of objects which had errors

get_ids()

   const std::vector<d_string>& InterSystems::LC_Batch::get_ids
   ( ) const [inline]
operator <<

   template<typename T>
   LC_Batch& InterSystems::LC_Batch::operator<<
   (  const d_ref< T > & obj) [inline] 
   template<typename T>
   LC_Batch& InterSystems::LC_Batch::operator<<
   (  const lc_d_ref< T > & obj) [inline]
   template<typename T> 
   LC_Batch& InterSystems::LC_Batch::operator<<
   (  T * obj) [inline]

Class InterSystems::d_query

Provides methods for preparing an SQL query, binding parameters, executing the query, and traversing the result set. For more information on this class, see Using Queries.

Constructor

d_query()

   InterSystems::d_query::d_query
   ( ) [inline]
   InterSystems::d_query::d_query
   (  Database * db) [inline]

Member list

close()

   bool abs_d_query::close
   ( ) [inherited] 
execute()

   void abs_d_query::execute
   ( ) [inherited] 
   void InterSystems::abs_d_query::execute
   (  const wchar_t * sql_query) [inline, inherited] 
fetch()

   bool InterSystems::d_seq_query::fetch
   ( ) [inline, inherited] 
get_col_name()

   const SQLWCHAR* InterSystems::abs_d_query::get_col_name
   (  int idx) const [inline, inherited] 
get_col_name_len()

   SQLSMALLINT InterSystems::abs_d_query::get_col_name_len
   (  int idx) const [inline, inherited] 
get_col_sql_type()

   SQLSMALLINT InterSystems::abs_d_query::get_col_sql_type
   (  int idx) const [inline, inherited] 
get_cur_idx()

   int InterSystems::d_seq_query::get_cur_idx
   ( ) const [inline, inherited] 
get_data()

   void d_seq_query::get_data
   (  char * buf, 
      int * size, 
      int cap, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  d_binary * val) [inherited] 
   void d_seq_query::get_data
   (  d_bool * val) [inherited] 
   void d_seq_query::get_data
   (  d_currency * val) [inherited] 
   void d_seq_query::get_data
   (  d_date * val) [inherited] 
   void d_seq_query::get_data
   (  d_double * val) [inherited] 
   void d_seq_query::get_data
   (  d_int * val) [inherited] 
   void d_seq_query::get_data
   (  d_string * val, 
      str_conv_t conv = NO_CONV 
   ) [inherited] 
   void d_seq_query::get_data
   (  d_time * val) [inherited] 
   void d_seq_query::get_data
   (  d_timestamp * val) [inherited] 
   void d_seq_query::get_data
   (  D_type * val) [inherited] 
   void d_seq_query::get_data
   (  d_wstring * val) [inherited] 
   void d_seq_query::get_data
   (  DATE_STRUCT * val, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  double * val, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  long * val, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  std::string * val, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  std::wstring * val, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  TIME_STRUCT * val, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  TIMESTAMP_STRUCT * val, 
      bool * is_nuol = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  void * buf, 
      int * size, 
      int cap, 
      bool * is_null = 0 
   ) [inherited] 
   void d_seq_query::get_data
   (  wchar_t * buf, 
      int * size, 
      int cap, 
      bool * is_null = 0 
   ) [inherited] 
   void InterSystems::d_seq_query::get_data
   (  bool * val, 
      bool * is_null = 0 
   ) [inline, inherited] 
get_job_id()

   int InterSystems::abs_d_query::get_job_id
   ( ) [inline, inherited] 
get_num_cols()

   int InterSystems::abs_d_query::get_num_cols
   ( ) const [inline, inherited] 
get_num_pars()

   int InterSystems::abs_d_query::get_num_pars
   ( ) const [inline, inherited] 
get_par_col_size()

   SQLUINTEGER InterSystems::abs_d_query::get_par_col_size
   (  int idx) const [inline, inherited] 
get_par_num_dec_digits()

   SQLSMALLINT InterSystems::abs_d_query::get_par_num_dec_digits
   (  int idx) const [inline, inherited] 
get_par_sql_type()

   SQLSMALLINT InterSystems::abs_d_query::get_par_sql_type
   (  int idx) const [inline, inherited] 
is_par_nullable()

   SQLSMALLINT InterSystems::abs_d_query::is_par_nullable
   (  int idx) const [inline, inherited] 
is_par_unbound()

   bool InterSystems::abs_d_query::is_par_unbound
   (  int idx) const [inline, inherited] 
prepare()

   void abs_d_query::prepare
   (  const char * cl_name, 
      const char * proc_name 
   ) [inherited] 
   void abs_d_query::prepare
   (  const char * sql_query, 
      int len 
   ) [inherited] 
   void abs_d_query::prepare
   (  const wchar_t * cl_name, 
      const wchar_t * proc_name 
   ) [inherited] 
   void abs_d_query::prepare
   (  const wchar_t * sql_query, 
      int len 
   ) [inherited] 
   void abs_d_query::prepare
   (  d_string & sql_name, 
      int num_pars 
   ) [inherited] 
   void InterSystems::abs_d_query::prepare
   (  const char * sql_query) [inline, inherited] 
   void InterSystems::abs_d_query::prepare
   (  const wchar_t * sql_query) [inline, inherited] 
set_cur_idx()

   void InterSystems::d_query::set_cur_idx
   (  int idx) [inline] 
set_par()

   void abs_d_query::set_par
   (  int idx) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const char * buf, 
      char_size_t size 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_binary & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_bool & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_currency & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_date & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_double & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_int & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_string & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_time & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_timestamp & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const D_type & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const d_wstring & val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const void * buf, 
      byte_size_t size 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      const wchar_t * buf, 
      char_size_t size 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      double val 
   ) [inherited] 
   void abs_d_query::set_par
   (  int idx, 
      int val 
   ) [inherited] 
   void InterSystems::abs_d_query::set_par
   (  int idx, 
      const char * val 
   ) [inline, inherited] 
   void InterSystems::abs_d_query::set_par
   (  int idx, 
      const std::string & val 
   ) [inline, inherited] 
   void InterSystems::abs_d_query::set_par
   (  int idx, 
      const std::wstring & val 
   ) [inline, inherited] 
   void InterSystems::abs_d_query::set_par
   (  int idx, 
      const wchar_t * val 
   ) [inline, inherited] 
set_par_default()

   void abs_d_query::set_par_default
   (  int idx) [inherited] 
set_stored_proc()

   void InterSystems::abs_d_query::set_stored_proc
   (  bool is_stored_proc) [inline, inherited] 
skip()

   void InterSystems::d_seq_query::skip
   (  unsigned int num_cols = 1) [inline, inherited] 
throw_err()

   void abs_d_query::throw_err
   (  SQLSMALLINT err_src, 
      SQLHANDLE handle 
   ) [static, inherited] 
unbind_pars()

   void abs_d_query::unbind_pars
   ( ) [inherited] 

Error Classes

Provides error reporting.

Class InterSystems::Db_err

See A Sample C++ Binding Application for an example that uses this class.

Constructor

Db_err()

   InterSystems::Db_err::Db_err
   ( ) [inline] 
   InterSystems::Db_err::Db_err
   (  int c) [inline] 
   InterSystems::Db_err::Db_err
   (  int c, 
      const char * m, 
      int l, 
      const char * s 
   ) [inline] 
   InterSystems::Db_err::Db_err
   (  int c, 
      const std::string & m 
   ) [inline] 
   InterSystems::Db_err::Db_err
   (  int c, 
      const std::string & m, 
      const char * s 
   ) [inline] 

Member list

clear()

   void InterSystems::Db_err::clear
   ( ) [inline] 
get()

   void Db_err::get
   (  t_istream & in) 
get_code()

   int InterSystems::Db_err::get_code
   ( ) const [inline] 
get_msg()

   const std::string& InterSystems::Db_err::get_msg
   ( ) const [inline] 
get_src()

   const std::string& InterSystems::Db_err::get_src
   ( ) const [inline] 
log()

   void Db_err::log
   ( ) const 
make_err_msg()

   std::string Db_err::make_err_msg
   (  const char * msg, 
      const char * arg1 = 0, 
      const char * arg2 = 0, 
      const char * arg3 = 0, 
      const char * arg4 = 0, 
      const char * arg5 = 0 
   ) [static] 
   std::string Db_err::make_err_msg
   (  const char * msg, 
      const wchar_t * arg1 = 0, 
      const wchar_t * arg2 = 0, 
      const wchar_t * arg3 = 0, 
      const wchar_t * arg4 = 0, 
      const wchar_t * arg5 = 0 
   ) [static] 
operator bool()

   InterSystems::Db_err::operator-bool
   ( ) const [inline] 
reset()

   void InterSystems::Db_err::reset
   (  int c, 
      const char * m 
   ) [inline] 
set_code()

   void InterSystems::Db_err::set_code
   (  int code) [inline] 
set_msg()

   void InterSystems::Db_err::set_msg
   (  const char * m) [inline] 
   void InterSystems::Db_err::set_msg
   (  const char * m, 
      int l 
   ) [inline] 
set_src()

   void InterSystems::Db_err::set_src
   (  const char * s) [inline] 
to_xml()

   void Db_err::to_xml
   (  xml_writer & out) const 
Feedback