1 #ifndef DOXYGEN_SHOULD_SKIP_THIS 2 3 #ifdef _ODBC // Enable Nanodbc only if an odbc driver was found 4 5 //! \file nanodbc.h The entirety of nanodbc can be found within this file and nanodbc.cpp. 6 7 //! \mainpage 8 //! 9 //! \section synopsis Synopsis 10 //! This library provides a wrapper API for the native ODBC API. It aims to do everything ODBC does, but with a \b much nicer interface. 11 //! Anything it doesn't (yet) do can be done by retrieving the native ODBC handles and dropping down to straight ODBC C API code. 12 //! For more propaganda, please see the <a href="http://lexicalunit.github.com/nanodbc/">project homepage</a>. 13 //! 14 //! \section toc Table of Contents 15 //! - \ref license "License" 16 //! - \ref credits "Credits" 17 //! - Source level documentation: 18 //! - \ref nanodbc "nanodbc namespace" 19 //! - \ref exceptions 20 //! - \ref utility 21 //! - \ref mainc 22 //! - \ref mainf 23 //! - \ref binding 24 //! - \ref bind_multi 25 //! - \ref bind_strings 26 //! 27 //! \section license License 28 //! <div class="license"> 29 //! Copyright (c) 2013 lexicalunit <lexicalunit@lexicalunit.com> 30 //! 31 //! The MIT License 32 //! 33 //! Permission is hereby granted, free of charge, to any person obtaining a copy 34 //! of this software and associated documentation files (the "Software"), to deal 35 //! in the Software without restriction, including without limitation the rights 36 //! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 37 //! copies of the Software, and to permit persons to whom the Software is 38 //! furnished to do so, subject to the following conditions: 39 //! 40 //! The above copyright notice and this permission notice shall be included in 41 //! all copies or substantial portions of the Software. 42 //! 43 //! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 44 //! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 45 //! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 46 //! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 47 //! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 48 //! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 49 //! THE SOFTWARE. 50 //! </div> 51 //! 52 //! \section credits Credits 53 //! <div class="license"> 54 //! Much of the code in this file was originally derived from TinyODBC. 55 //! TinyODBC is hosted at http://code.google.com/p/tiodbc/ 56 //! Copyright (c) 2008 SqUe squarious@gmail.com 57 //! License: The MIT License 58 //! 59 //! The idea for using RAII for transactions was inspired by SimpleDB: C++ ODBC database API, 60 //! however the code in nanodbc is original and not derived from SimpleDB. Therefore 61 //! the LGPL license under which SimpleDB is distributed does NOT apply to nanodbc. 62 //! SimpleDB is hosted at http://simpledb.sourceforge.net 63 //! Copyright (c) 2006 Eminence Technology Pty Ltd 64 //! Copyright (c) 2008-2010,2012 Russell Kliese russell@kliese.id.au 65 //! License: GNU Lesser General Public version 2.1 66 //! 67 //! Some improvements and features are based on The Python ODBC Library. 68 //! The Python ODBC Library is hosted at http://code.google.com/p/pyodbc/ 69 //! License: The MIT License 70 //! 71 //! Implementation of column binding inspired by Nick E. Geht's source code posted to on CodeGuru. 72 //! GSODBC hosted at http://www.codeguru.com/mfc_database/gsodbc.html 73 //! Copyright (c) 2002 Nick E. Geht 74 //! License: Perpetual license to reproduce, distribute, adapt, perform, display, and sublicense. 75 //! See http://www.codeguru.com/submission-guidelines.php for details. 76 //! </div> 77 78 #ifndef NANODBC_H 79 #define NANODBC_H 80 81 #include <functional> 82 #include <memory> 83 #include <stdexcept> 84 #include <string> 85 #include <vector> 86 87 #ifndef __clang__ 88 #include <cstdint> 89 #endif 90 91 //! \brief The entirety of nanodbc can be found within this one namespace. 92 //! \note This library does not make any exception safety guarantees, but should work just fine with a threading enabled ODBC driver. If you want to use nanodbc objects in threads I recommend each thread keep their own connection to the database. Otherwise you must synchronize any access to nanodbc objects. 93 namespace nanodbc 94 { 95 96 // .d8888b. .d888 d8b 888 d8b 97 // d88P Y88b d88P" Y8P 888 Y8P 98 // 888 888 888 888 99 // 888 .d88b. 88888b. 888888 888 .d88b. 888 888 888d888 8888b. 888888 888 .d88b. 88888b. 100 // 888 d88""88b 888 "88b 888 888 d88P"88b 888 888 888P" "88b 888 888 d88""88b 888 "88b 101 // 888 888 888 888 888 888 888 888 888 888 888 888 888 .d888888 888 888 888 888 888 888 102 // Y88b d88P Y88..88P 888 888 888 888 Y88b 888 Y88b 888 888 888 888 Y88b. 888 Y88..88P 888 888 103 // "Y8888P" "Y88P" 888 888 888 888 "Y88888 "Y88888 888 "Y888888 "Y888 888 "Y88P" 888 888 104 // 888 105 // Y8b d88P 106 // "Y88P" 107 // MARK: Configuration - 108 109 //! \addtogroup macros Macros 110 //! \brief Macros that nanodbc uses, can be overriden by users. 111 //! 112 //! @{ 113 114 #ifdef DOXYGEN 115 //! \def NANODBC_ASSERT(expression) 116 //! \brief Assertion. 117 //! 118 //! By default, nanodbc uses C \c assert() for internal assertions. 119 //! User can override it by defining \c NANODBC_ASSERT(expr) macro 120 //! in the nanodbc.h file and customizing it as desired, 121 //! before building the library. 122 //! 123 //! \code{.cpp} 124 //! #ifdef _DEBUG 125 //! #include <crtdbg.h> 126 //! #define NANODBC_ASSERT _ASSERTE 127 //! #endif 128 //! \endcode 129 #define NANODBC_ASSERT(expression) assert(expression) 130 #endif 131 132 //! @} 133 134 // You must explicitly request Unicode support by defining NANODBC_USE_UNICODE at compile time. 135 #ifndef DOXYGEN 136 #ifdef NANODBC_USE_UNICODE 137 #ifdef NANODBC_USE_IODBC_WIDE_STRINGS 138 typedef std::u32string string_type; 139 #else 140 typedef std::u16string string_type; 141 #endif 142 #else 143 typedef std::string string_type; 144 #endif // NANODBC_USE_UNICODE 145 146 #if defined(_WIN64) 147 // LLP64 machine: Windows 148 typedef std::int64_t null_type; 149 #elif !defined(_WIN64) && defined( __LP64__) 150 // LP64 machine: OS X or Linux 151 typedef long null_type; 152 #else 153 // 32-bit machine 154 typedef long null_type; 155 #endif 156 #else 157 //! \c string_type will be \c std::u16string or \c std::32string if \c NANODBC_USE_UNICODE is defined, otherwise \c std::string. 158 typedef unspecified-type string_type; 159 //! \c null_type will be \c int64_t for 64-bit compilations, otherwise \c long. 160 typedef unspecified-type null_type; 161 #endif // DOXYGEN 162 163 #if defined(_MSC_VER) && _MSC_VER <= 1800 164 // These versions of Visual C++ do not yet support \c noexcept or \c std::move. 165 #define NANODBC_NOEXCEPT 166 #define NANODBC_NO_MOVE_CTOR 167 #else 168 #define NANODBC_NOEXCEPT noexcept 169 #endif 170 171 // 8888888888 888 888 888 888 d8b 172 // 888 888 888 888 888 Y8P 173 // 888 888 888 888 888 174 // 8888888 888d888 888d888 .d88b. 888d888 8888888888 8888b. 88888b. .d88888 888 888 88888b. .d88b. 175 // 888 888P" 888P" d88""88b 888P" 888 888 "88b 888 "88b d88" 888 888 888 888 "88b d88P"88b 176 // 888 888 888 888 888 888 888 888 .d888888 888 888 888 888 888 888 888 888 888 888 177 // 888 888 888 Y88..88P 888 888 888 888 888 888 888 Y88b 888 888 888 888 888 Y88b 888 178 // 8888888888 888 888 "Y88P" 888 888 888 "Y888888 888 888 "Y88888 888 888 888 888 "Y88888 179 // 888 180 // Y8b d88P 181 // "Y88P" 182 // MARK: Error Handling - 183 184 //! \addtogroup exceptions Exception types 185 //! \brief Possible error conditions. 186 //! 187 //! Specific errors such as \c type_incompatible_error, \c null_access_error, and \c index_range_error can arise 188 //! from improper use of the nanodbc library. The general \c database_error is for all other situations 189 //! in which the ODBC driver or C API reports an error condition. The explanatory string for database_error 190 //! will, if possible, contain a diagnostic message obtained from \c SQLGetDiagRec(). 191 //! @{ 192 193 //! \brief Type incompatible. 194 //! \see exceptions 195 class type_incompatible_error : public std::runtime_error 196 { 197 public: 198 type_incompatible_error(); 199 const char* what() const NANODBC_NOEXCEPT; 200 }; 201 202 //! \brief Accessed null data. 203 //! \see exceptions 204 class null_access_error : public std::runtime_error 205 { 206 public: 207 null_access_error(); 208 const char* what() const NANODBC_NOEXCEPT; 209 }; 210 211 //! \brief Index out of range. 212 //! \see exceptions 213 class index_range_error : public std::runtime_error 214 { 215 public: 216 index_range_error(); 217 const char* what() const NANODBC_NOEXCEPT; 218 }; 219 220 //! \brief Programming logic error. 221 //! \see exceptions 222 class programming_error : public std::runtime_error 223 { 224 public: 225 explicit programming_error(const std::string& info); 226 const char* what() const NANODBC_NOEXCEPT; 227 }; 228 229 //! \brief General database error. 230 //! \see exceptions 231 class database_error : public std::runtime_error 232 { 233 public: 234 //! \brief Creates a runtime_error with a message describing the last ODBC error generated for the given handle and handle_type. 235 //! \param handle The native ODBC statement or connection handle. 236 //! \param handle_type The native ODBC handle type code for the given handle. 237 //! \param info Additional information that will be appended to the beginning of the error message. 238 database_error(void* handle, short handle_type, const std::string& info = ""); 239 const char* what() const NANODBC_NOEXCEPT; 240 const long native() const NANODBC_NOEXCEPT; 241 const std::string state() const NANODBC_NOEXCEPT; 242 private: 243 long native_error; 244 std::string sql_state; 245 std::string message; 246 }; 247 248 //! @} 249 250 // 888 888 888 d8b 888 d8b 888 d8b 251 // 888 888 888 Y8P 888 Y8P 888 Y8P 252 // 888 888 888 888 888 253 // 888 888 888888 888 888 888 888888 888 .d88b. .d8888b 254 // 888 888 888 888 888 888 888 888 d8P Y8b 88K 255 // 888 888 888 888 888 888 888 888 88888888 "Y8888b. 256 // Y88b. .d88P Y88b. 888 888 888 Y88b. 888 Y8b. X88 257 // "Y88888P" "Y888 888 888 888 "Y888 888 "Y8888 88888P' 258 // MARK: Utilities - 259 260 //! \addtogroup utility Utilities 261 //! \brief Additional nanodbc utility classes and functions. 262 //! 263 //! \{ 264 265 //! \brief A type for representing date data. 266 struct date 267 { 268 std::int16_t year; //!< Year [0-inf). 269 std::int16_t month; //!< Month of the year [1-12]. 270 std::int16_t day; //!< Day of the month [1-31]. 271 }; 272 273 //! \brief A type for representing timestamp data. 274 struct timestamp 275 { 276 std::int16_t year; //!< Year [0-inf). 277 std::int16_t month; //!< Month of the year [1-12]. 278 std::int16_t day; //!< Day of the month [1-31]. 279 std::int16_t hour; //!< Hours since midnight [0-23]. 280 std::int16_t min; //!< Minutes after the hour [0-59]. 281 std::int16_t sec; //!< Seconds after the minute. 282 std::int32_t fract; //!< Fractional seconds. 283 }; 284 285 //! \} 286 287 //! \addtogroup mainc Main classes 288 //! \brief Main nanodbc classes. 289 //! 290 //! @{ 291 292 // 88888888888 888 d8b 293 // 888 888 Y8P 294 // 888 888 295 // 888 888d888 8888b. 88888b. .d8888b 8888b. .d8888b 888888 888 .d88b. 88888b. 296 // 888 888P" "88b 888 "88b 88K "88b d88P" 888 888 d88""88b 888 "88b 297 // 888 888 .d888888 888 888 "Y8888b. .d888888 888 888 888 888 888 888 888 298 // 888 888 888 888 888 888 X88 888 888 Y88b. Y88b. 888 Y88..88P 888 888 299 // 888 888 "Y888888 888 888 88888P' "Y888888 "Y8888P "Y888 888 "Y88P" 888 888 300 // MARK: Transaction - 301 302 //! \brief A resource for managing transaction commits and rollbacks. 303 //! 304 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 305 class transaction 306 { 307 public: 308 //! \brief Begin a transaction on the given connection object. 309 //! \post Operations that modify the database must now be committed before taking effect. 310 //! \throws database_error 311 explicit transaction(const class connection& conn); 312 313 //! Copy constructor. 314 transaction(const transaction& rhs); 315 316 #ifndef NANODBC_NO_MOVE_CTOR 317 //! Move constructor. 318 transaction(transaction&& rhs) NANODBC_NOEXCEPT; 319 #endif 320 321 //! Assignment. 322 transaction& operator=(transaction rhs); 323 324 //! Member swap. 325 void swap(transaction& rhs) NANODBC_NOEXCEPT; 326 327 //! \brief If this transaction has not been committed, will will rollback any modifying operations. 328 ~transaction() NANODBC_NOEXCEPT; 329 330 //! \brief Marks this transaction for commit. 331 //! \throws database_error 332 void commit(); 333 334 //! \brief Marks this transaction for rollback. 335 void rollback() NANODBC_NOEXCEPT; 336 337 //! Returns the connection object. 338 class connection& connection(); 339 340 //! Returns the connection object. 341 const class connection& connection() const; 342 343 //! Returns the connection object. 344 operator class connection&(); 345 346 //! Returns the connection object. 347 operator const class connection&() const; 348 349 private: 350 class transaction_impl; 351 friend class nanodbc::connection; 352 353 private: 354 std::shared_ptr<transaction_impl> impl_; 355 }; 356 357 // .d8888b. 888 888 888 358 // d88P Y88b 888 888 888 359 // Y88b. 888 888 888 360 // "Y888b. 888888 8888b. 888888 .d88b. 88888b.d88b. .d88b. 88888b. 888888 361 // "Y88b. 888 "88b 888 d8P Y8b 888 "888 "88b d8P Y8b 888 "88b 888 362 // "888 888 .d888888 888 88888888 888 888 888 88888888 888 888 888 363 // Y88b d88P Y88b. 888 888 Y88b. Y8b. 888 888 888 Y8b. 888 888 Y88b. 364 // "Y8888P" "Y888 "Y888888 "Y888 "Y8888 888 888 888 "Y8888 888 888 "Y888 365 // MARK: Statement - 366 367 //! \brief Represents a statement on the database. 368 class statement 369 { 370 public: 371 //! \brief Provides support for retrieving output/return parameters. 372 //! \see binding 373 enum param_direction 374 { 375 PARAM_IN //!< Binding an input parameter. 376 , PARAM_OUT //!< Binding an output parameter. 377 , PARAM_INOUT //!< Binding an input/output parameter. 378 , PARAM_RETURN //!< Binding a return parameter. 379 }; 380 381 public: 382 //! \brief Creates a new un-prepared statement. 383 //! \see execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare() 384 statement(); 385 386 //! \brief Constructs a statement object and associates it to the given connection. 387 //! \param conn The connection to use. 388 //! \see open(), prepare() 389 explicit statement(class connection& conn); 390 391 //! \brief Constructs and prepares a statement using the given connection and query. 392 //! \param conn The connection to use. 393 //! \param query The SQL query statement. 394 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 395 //! \see execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare() 396 statement(class connection& conn, const string_type& query, long timeout = 0); 397 398 //! Copy constructor. 399 statement(const statement& rhs); 400 401 #ifndef NANODBC_NO_MOVE_CTOR 402 //! Move constructor. 403 statement(statement&& rhs) NANODBC_NOEXCEPT; 404 #endif 405 406 //! Assignment. 407 statement& operator=(statement rhs); 408 409 //! Member swap. 410 void swap(statement& rhs) NANODBC_NOEXCEPT; 411 412 //! \brief Closes the statement. 413 //! \see close() 414 ~statement() NANODBC_NOEXCEPT; 415 416 //! \brief Creates a statement for the given connection. 417 //! \param conn The connection where the statement will be executed. 418 //! \throws database_error 419 void open(class connection& conn); 420 421 //! \brief Returns true if connection is open. 422 bool open() const; 423 424 //! \brief Returns true if connected to the database. 425 bool connected() const; 426 427 //! \brief Returns the associated connection object if any. 428 class connection& connection(); 429 430 //! \brief Returns the associated connection object if any. 431 const class connection& connection() const; 432 433 //! \brief Returns the native ODBC statement handle. 434 void* native_statement_handle() const; 435 436 //! \brief Closes the statement and frees all associated resources. 437 void close(); 438 439 //! \brief Cancels execution of the statement. 440 //! \throws database_error 441 void cancel(); 442 443 //! \brief Opens and prepares the given statement to execute on the given connection. 444 //! \param conn The connection where the statement will be executed. 445 //! \param query The SQL query that will be executed. 446 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 447 //! \see open() 448 //! \throws database_error 449 void prepare(class connection& conn, const string_type& query, long timeout = 0); 450 451 //! \brief Prepares the given statement to execute its associated connection. 452 //! If the statement is not open throws programming_error. 453 //! \param query The SQL query that will be executed. 454 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 455 //! \see open() 456 //! \throws database_error, programming_error 457 void prepare(const string_type& query, long timeout = 0); 458 459 //! \brief Sets the number in seconds before query timeout. Default is 0 indicating no timeout. 460 //! \throws database_error 461 void timeout(long timeout = 0); 462 463 //! \brief Immediately opens, prepares, and executes the given query directly on the given connection. 464 //! \param conn The connection where the statement will be executed. 465 //! \param query The SQL query that will be executed. 466 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 467 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 468 //! \return A result set object. 469 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 470 //! \see open(), prepare(), execute(), result, transaction 471 class result execute_direct(class connection& conn, const string_type& query, long batch_operations = 1, long timeout = 0); 472 473 //! \brief Immediately opens, prepares, and executes the given query directly on the given connection, in asynchronous mode. 474 //! 475 //! This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. 476 //! Such that the identifiers `SQL_ATTR_ASYNC_STMT_EVENT` and `SQLCompleteAsync` are extant. Otherwise 477 //! this method will be defined, but not implemented. 478 //! 479 //! \param conn The connection where the statement will be executed. 480 //! \param event_handle The event handle for which the caller will wait before calling async_complete. 481 //! \param query The SQL query that will be executed. 482 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 483 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 484 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 485 //! \see open(), prepare(), execute(), result, transaction 486 void async_execute_direct(class connection& conn, void* event_handle, const string_type& query, long batch_operations = 1, long timeout = 0); 487 488 //! \brief Completes a previously initiated asynchronous query operation, returning the result. 489 //! 490 //! This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. 491 //! Such that the identifiers `SQL_ATTR_ASYNC_STMT_EVENT` and `SQLCompleteAsync` are extant. Otherwise 492 //! this method will be defined, but not implemented. 493 //! 494 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 495 class result async_complete(long batch_operations = 1); 496 497 //! \brief Execute the previously prepared query now without constructing result object. 498 //! \param conn The connection where the statement will be executed. 499 //! \param query The SQL query that will be executed. 500 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 501 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 502 //! \throws database_error 503 //! \return A result set object. 504 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 505 //! \see open(), prepare(), execute(), execute_direct(), result, transaction 506 void just_execute_direct(class connection& conn, const string_type& query, long batch_operations = 1, long timeout = 0); 507 508 //! \brief Execute the previously prepared query now. 509 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 510 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 511 //! \throws database_error 512 //! \return A result set object. 513 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 514 //! \see open(), prepare(), result, transaction 515 class result execute(long batch_operations = 1, long timeout = 0); 516 517 //! \brief Execute the previously prepared query now without constructing result object. 518 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 519 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 520 //! \throws database_error 521 //! \return A result set object. 522 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 523 //! \see open(), prepare(), execute(), result, transaction 524 void just_execute(long batch_operations = 1, long timeout = 0); 525 526 //! \brief Returns the input and output paramters of the specified stored procedure. 527 //! \param catalog The catalog name of the procedure. 528 //! \param schema Pattern to use for schema names. 529 //! \param procedure The name of the procedure. 530 //! \param column Pattern to use for column names. 531 //! \throws database_error 532 //! \return A result set object. 533 class result procedure_columns(const string_type& catalog, const string_type& schema, const string_type& procedure, const string_type& column); 534 535 //! \brief Returns the number of rows affected by the request or -1 if the number of affected rows is not available. 536 //! \throws database_error 537 long affected_rows() const; 538 539 //! \brief Returns the number of columns in a result set. 540 //! \throws database_error 541 short columns() const; 542 543 //! \brief Resets all currently bound parameters. 544 void reset_parameters() NANODBC_NOEXCEPT; 545 546 //! \brief Returns the parameter size for the indicated parameter placeholder within a prepared statement. 547 unsigned long parameter_size(short param) const; 548 549 //! \addtogroup binding Binding parameters 550 //! \brief These functions are used to bind values to ODBC parameters. 551 //! 552 //! @{ 553 554 //! \brief Binds the given value to the given parameter placeholder number in the prepared statement. 555 //! 556 //! If your prepared SQL query has any ? placeholders, this is how you bind values to them. 557 //! Placeholder numbers count from left to right and are 0-indexed. 558 //! 559 //! It is NOT possible to use these functions for bulk operations as number of elements is not specified here. 560 //! 561 //! \param param Placeholder position. 562 //! \param value Value to substitute into placeholder. 563 //! \param direction ODBC parameter direction. 564 //! \throws database_error 565 template<class T> 566 void bind(short param, const T* value, param_direction direction = PARAM_IN); 567 568 //! \addtogroup bind_multi Binding multiple non-string values 569 //! \brief Binds the given values to the given parameter placeholder number in the prepared statement. 570 //! 571 //! If your prepared SQL query has any ? placeholders, this is how you bind values to them. 572 //! Placeholder numbers count from left to right and are 0-indexed. 573 //! 574 //! It is possible to use these functions for bulk operations. 575 //! 576 //! \param param Placeholder position. 577 //! \param values Values to substitute into placeholder. 578 //! \param elements The number of elements being bound. 579 //! \param null_sentry Value which should represent a null value. 580 //! \param nulls Flags for values that should be set to a null value. 581 //! \param param_direciton ODBC parameter direction. 582 //! \throws database_error 583 //! 584 //! @{ 585 586 //! \brief Binds multiple values. 587 //! \see bind_multi 588 template<class T> 589 void bind(short param, const T* values, std::size_t elements, param_direction direction = PARAM_IN); 590 591 //! \brief Binds multiple values. 592 //! \see bind_multi 593 template<class T> 594 void bind(short param, const T* values, std::size_t elements, const T* null_sentry, param_direction direction = PARAM_IN); 595 596 //! \brief Binds multiple values. 597 //! \see bind_multi 598 template<class T> 599 void bind(short param, const T* values, std::size_t elements, const bool* nulls, param_direction direction = PARAM_IN); 600 601 //! @} 602 603 //! \addtogroup bind_strings Binding multiple string values 604 //! \brief Binds the given string values to the given parameter placeholder number in the prepared statement. 605 //! 606 //! If your prepared SQL query has any ? placeholders, this is how you bind values to them. 607 //! Placeholder numbers count from left to right and are 0-indexed. 608 //! 609 //! It is possible to use these functions for bulk operations. 610 //! 611 //! \param param Placeholder position. 612 //! \param values Values to substitute into placeholder. 613 //! \param length Maximum length of string elements. 614 //! \param elements The number of elements being bound. Otherwise the value N is taken as the number of elements. 615 //! \param null_sentry Value which should represent a null value. 616 //! \param nulls Flags for values that should be set to a null value. 617 //! \param param_direciton ODBC parameter direction. 618 //! \throws database_error 619 //! 620 //! @{ 621 622 //! \brief Binds multiple string values. 623 //! \see bind_strings 624 void bind_strings( 625 short param 626 , const string_type::value_type* values 627 , std::size_t length 628 , std::size_t elements 629 , param_direction direction = PARAM_IN); 630 631 //! \brief Binds multiple string values. 632 //! \see bind_strings 633 template<std::size_t N, std::size_t M> 634 void bind_strings( 635 short param 636 , const string_type::value_type(&values)[N][M] 637 , param_direction direction = PARAM_IN) 638 { 639 bind_strings( 640 param 641 , reinterpret_cast<const string_type::value_type*>(values) 642 , M 643 , N 644 , direction); 645 } 646 647 //! \brief Binds multiple string values. 648 //! \see bind_strings 649 void bind_strings( 650 short param 651 , const string_type::value_type* values 652 , std::size_t length 653 , std::size_t elements 654 , const string_type::value_type* null_sentry 655 , param_direction direction = PARAM_IN); 656 657 //! \brief Binds multiple string values. 658 //! \see bind_strings 659 template<std::size_t N, std::size_t M> 660 void bind_strings( 661 short param 662 , const string_type::value_type(&values)[N][M] 663 , const string_type::value_type* null_sentry 664 , param_direction direction = PARAM_IN) 665 { 666 bind_strings( 667 param 668 , reinterpret_cast<const string_type::value_type*>(values) 669 , M 670 , N 671 , null_sentry 672 , direction); 673 } 674 675 //! \brief Binds multiple string values. 676 //! \see bind_strings 677 void bind_strings( 678 short param 679 , const string_type::value_type* values 680 , std::size_t length 681 , std::size_t elements 682 , const bool* nulls 683 , param_direction direction = PARAM_IN); 684 685 //! \brief Binds multiple string values. 686 //! \see bind_strings 687 template<std::size_t N, std::size_t M> 688 void bind_strings( 689 short param 690 , const string_type::value_type(&values)[N][M] 691 , const bool* nulls 692 , param_direction direction = PARAM_IN) 693 { 694 bind_strings( 695 param 696 , reinterpret_cast<const string_type::value_type*>(values) 697 , M 698 , N 699 , nulls 700 , direction); 701 } 702 703 //! @} 704 705 //! \brief Binds null values to the given parameter placeholder number in the prepared statement. 706 //! 707 //! If your prepared SQL query has any ? placeholders, this is how you bind values to them. 708 //! Placeholder numbers count from left to right and are 0-indexed. 709 //! 710 //! It is possible to use this function for bulk operations. 711 //! 712 //! \param param Placeholder position. 713 //! \param elements The number of elements being bound. 714 //! \throws database_error 715 void bind_null(short param, std::size_t elements = 1); 716 717 //! @} 718 719 private: 720 typedef std::function<bool (std::size_t)> null_predicate_type; 721 722 private: 723 class statement_impl; 724 friend class nanodbc::result; 725 726 private: 727 std::shared_ptr<statement_impl> impl_; 728 }; 729 730 // .d8888b. 888 d8b 731 // d88P Y88b 888 Y8P 732 // 888 888 888 733 // 888 .d88b. 88888b. 88888b. .d88b. .d8888b 888888 888 .d88b. 88888b. 734 // 888 d88""88b 888 "88b 888 "88b d8P Y8b d88P" 888 888 d88""88b 888 "88b 735 // 888 888 888 888 888 888 888 888 88888888 888 888 888 888 888 888 888 736 // Y88b d88P Y88..88P 888 888 888 888 Y8b. Y88b. Y88b. 888 Y88..88P 888 888 737 // "Y8888P" "Y88P" 888 888 888 888 "Y8888 "Y8888P "Y888 888 "Y88P" 888 888 738 // MARK: Connection - 739 740 //! \brief Manages and encapsulates ODBC resources such as the connection and environment handles. 741 class connection 742 { 743 public: 744 //! \brief Create new connection object, initially not connected. 745 connection(); 746 747 //! Copy constructor. 748 connection(const connection& rhs); 749 750 #ifndef NANODBC_NO_MOVE_CTOR 751 //! Move constructor. 752 connection(connection&& rhs) NANODBC_NOEXCEPT; 753 #endif 754 755 //! Assignment. 756 connection& operator=(connection rhs); 757 758 //! Member swap. 759 void swap(connection&) NANODBC_NOEXCEPT; 760 761 //! \brief Create new connection object and immediately connect to the given data source. 762 //! \param dsn The name of the data source. 763 //! \param user The username for authenticating to the data source. 764 //! \param pass The password for authenticating to the data source. 765 //! \param timeout The number in seconds before connection timeout. Default is 0 indicating no timeout. 766 //! \throws database_error 767 //! \see connected(), connect() 768 connection( 769 const string_type& dsn 770 , const string_type& user 771 , const string_type& pass 772 , long timeout = 0); 773 774 //! \brief Create new connection object and immediately connect using the given connection string. 775 //! \param connection_string The connection string for establishing a connection. 776 //! \param timeout The number in seconds before connection timeout. Default is 0 indicating no timeout. 777 //! \throws database_error 778 //! \see connected(), connect() 779 connection(const string_type& connection_string, long timeout = 0); 780 781 //! \brief Automatically disconnects from the database and frees all associated resources. 782 //! 783 //! Will not throw even if disconnecting causes some kind of error and raises an exception. 784 //! If you explicitly need to know if disconnect() succeeds, call it directly. 785 ~connection() NANODBC_NOEXCEPT; 786 787 //! \brief Connect to the given data source. 788 //! \param dsn The name of the data source. 789 //! \param user The username for authenticating to the data source. 790 //! \param pass The password for authenticating to the data source. 791 //! \param timeout The number in seconds before connection timeout. Default is 0 indicating no timeout. 792 //! \throws database_error 793 //! \see connected() 794 void connect( 795 const string_type& dsn 796 , const string_type& user 797 , const string_type& pass 798 , long timeout = 0); 799 800 //! \brief Connect using the given connection string. 801 //! \param connection_string The connection string for establishing a connection. 802 //! \param timeout The number in seconds before connection timeout. Default is 0 indicating no timeout. 803 //! \throws database_error 804 //! \see connected() 805 void connect(const string_type& connection_string, long timeout = 0); 806 807 //! \brief Initiate an asynchronous connection operation to the given data source. 808 //! 809 //! This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. 810 //! Such that the identifiers `SQL_ATTR_ASYNC_DBC_EVENT` and `SQLCompleteAsync` are extant. Otherwise 811 //! this method will be defined, but not implemented. 812 //! 813 //! \param dsn The name of the data source. 814 //! \param user The username for authenticating to the data source. 815 //! \param pass The password for authenticating to the data source. 816 //! \param event_handle The event handle for which the caller will wait before calling async_complete. 817 //! \param timeout The number in seconds before connection timeout. Default is 0 indicating no timeout. 818 //! \throws database_error 819 //! \see connected() 820 void async_connect( 821 const string_type& dsn 822 , const string_type& user 823 , const string_type& pass 824 , void* event_handle 825 , long timeout = 0); 826 827 //! \brief Initiate an asynchronous connection operation using the given connection string. 828 //! 829 //! This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. 830 //! Such that the identifiers `SQL_ATTR_ASYNC_DBC_EVENT` and `SQLCompleteAsync` are extant. Otherwise 831 //! this method will be defined, but not implemented. 832 //! 833 //! \param connection_string The connection string for establishing a connection. 834 //! \param event_handle The event handle for which the caller will wait before calling async_complete. 835 //! \param timeout The number in seconds before connection timeout. Default is 0 indicating no timeout. 836 //! \throws database_error 837 //! \see connected() 838 void async_connect(const string_type& connection_string, void* event_handle, long timeout = 0); 839 840 //! \brief Completes a previously initiated asynchronous connection operation. 841 void async_complete(); 842 843 //! \brief Returns true if connected to the database. 844 bool connected() const; 845 846 //! \brief Disconnects from the database, but maintains environment and handle resources. 847 void disconnect(); 848 849 //! \brief Returns the number of transactions currently held for this connection. 850 std::size_t transactions() const; 851 852 //! \brief Returns the native ODBC database connection handle. 853 void* native_dbc_handle() const; 854 855 //! \brief Returns the native ODBC environment handle. 856 void* native_env_handle() const; 857 858 //! \brief Returns name of the DBMS product. 859 //! Returns the ODBC information type SQL_DBMS_NAME of the DBMS product 860 //! accesssed by the driver via the current connection. 861 string_type dbms_name() const; 862 863 //! \brief Returns version of the DBMS product. 864 //! Returns the ODBC information type SQL_DBMS_VER of the DBMS product 865 //! accesssed by the driver via the current connection. 866 string_type dbms_version() const; 867 868 //! \brief Returns the name of the ODBC driver. 869 //! \throws database_error 870 string_type driver_name() const; 871 872 //! \brief Returns the name of the currently connected database. 873 //! Returns the current SQL_DATABASE_NAME information value associated with the connection. 874 string_type database_name() const; 875 876 //! \brief Returns the name of the current catalog. 877 //! Returns the current setting of the connection attribute SQL_ATTR_CURRENT_CATALOG. 878 string_type catalog_name() const; 879 880 private: 881 std::size_t ref_transaction(); 882 std::size_t unref_transaction(); 883 bool rollback() const; 884 void rollback(bool onoff); 885 886 private: 887 class connection_impl; 888 friend class nanodbc::transaction::transaction_impl; 889 890 private: 891 std::shared_ptr<connection_impl> impl_; 892 }; 893 894 // 8888888b. 888 888 895 // 888 Y88b 888 888 896 // 888 888 888 888 897 // 888 d88P .d88b. .d8888b 888 888 888 888888 898 // 8888888P" d8P Y8b 88K 888 888 888 888 899 // 888 T88b 88888888 "Y8888b. 888 888 888 888 900 // 888 T88b Y8b. X88 Y88b 888 888 Y88b. 901 // 888 T88b "Y8888 88888P' "Y88888 888 "Y888 902 // MARK: Result - 903 904 class catalog; 905 906 //! \brief A resource for managing result sets from statement execution. 907 //! 908 //! \see statement::execute(), statement::execute_direct() 909 //! \note result objects may be copied, however all copies will refer to the same underlying ODBC result set. 910 class result 911 { 912 public: 913 //! Empty result set. 914 result(); 915 916 //! Free result set. 917 ~result() NANODBC_NOEXCEPT; 918 919 //! Copy constructor. 920 result(const result& rhs); 921 922 #ifndef NANODBC_NO_MOVE_CTOR 923 //! Move constructor. 924 result(result&& rhs) NANODBC_NOEXCEPT; 925 #endif 926 927 //! Assignment. 928 result& operator=(result rhs); 929 930 //! Member swap. 931 void swap(result& rhs) NANODBC_NOEXCEPT; 932 933 //! \brief Returns the native ODBC statement handle. 934 void* native_statement_handle() const; 935 936 //! \brief The rowset size for this result set. 937 long rowset_size() const NANODBC_NOEXCEPT; 938 939 //! \brief Returns the number of rows affected by the request or -1 if the number of affected rows is not available. 940 //! \throws database_error 941 long affected_rows() const; 942 943 //! \brief Returns the number of rows in the current rowset or 0 if the number of rows is not available. 944 long rows() const NANODBC_NOEXCEPT; 945 946 //! \brief Returns the number of columns in a result set. 947 //! \throws database_error 948 short columns() const; 949 950 //! \brief Fetches the first row in the current result set. 951 //! \return true if there are more results or false otherwise. 952 //! \throws database_error 953 bool first(); 954 955 //! \brief Fetches the last row in the current result set. 956 //! \return true if there are more results or false otherwise. 957 //! \throws database_error 958 bool last(); 959 960 //! \brief Fetches the next row in the current result set. 961 //! \return true if there are more results or false otherwise. 962 //! \throws database_error 963 bool next(); 964 965 //! \brief Fetches the prior row in the current result set. 966 //! \return true if there are more results or false otherwise. 967 //! \throws database_error 968 bool prior(); 969 970 //! \brief Moves to and fetches the specified row in the current result set. 971 //! \return true if there are results or false otherwise. 972 //! \throws database_error 973 bool move(long row); 974 975 //! \brief Skips a number of rows and then fetches the resulting row in the current result set. 976 //! \return true if there are results or false otherwise. 977 //! \throws database_error 978 bool skip(long rows); 979 980 //! \brief Returns the row position in the current result set. 981 unsigned long position() const; 982 983 //! \brief Returns true if there are no more results in the current result set. 984 bool end() const NANODBC_NOEXCEPT; 985 986 //! \brief Gets data from the given column of the current rowset. 987 //! 988 //! Columns are numbered from left to right and 0-indexed. 989 //! \param column position. 990 //! \param result The column's value will be written to this parameter. 991 //! \throws database_error, index_range_error, type_incompatible_error, null_access_error 992 template<class T> 993 void get_ref(short column, T& result) const; 994 995 //! \brief Gets data from the given column of the current rowset. 996 //! If the data is null, fallback is returned instead. 997 //! 998 //! Columns are numbered from left to right and 0-indexed. 999 //! \param column position. 1000 //! \param fallback if value is null, return fallback instead. 1001 //! \param result The column's value will be written to this parameter. 1002 //! \throws database_error, index_range_error, type_incompatible_error 1003 template<class T> 1004 void get_ref(short column, const T& fallback, T& result) const; 1005 1006 //! \brief Gets data from the given column by name of the current rowset. 1007 //! 1008 //! \param column_name column's name. 1009 //! \param result The column's value will be written to this parameter. 1010 //! \throws database_error, index_range_error, type_incompatible_error, null_access_error 1011 template<class T> 1012 void get_ref(const string_type& column_name, T& result) const; 1013 1014 //! \brief Gets data from the given column by name of the current rowset. 1015 //! If the data is null, fallback is returned instead. 1016 //! 1017 //! \param column_name column's name. 1018 //! \param fallback if value is null, return fallback instead. 1019 //! \param result The column's value will be written to this parameter. 1020 //! \throws database_error, index_range_error, type_incompatible_error 1021 template<class T> 1022 void get_ref(const string_type& column_name, const T& fallback, T& result) const; 1023 1024 //! \brief Gets data from the given column of the current rowset. 1025 //! 1026 //! Columns are numbered from left to right and 0-indexed. 1027 //! \param column position. 1028 //! \throws database_error, index_range_error, type_incompatible_error, null_access_error 1029 template<class T> 1030 T get(short column) const; 1031 1032 //! \brief Gets data from the given column of the current rowset. 1033 //! If the data is null, fallback is returned instead. 1034 //! 1035 //! Columns are numbered from left to right and 0-indexed. 1036 //! \param column position. 1037 //! \param fallback if value is null, return fallback instead. 1038 //! \throws database_error, index_range_error, type_incompatible_error 1039 template<class T> 1040 T get(short column, const T& fallback) const; 1041 1042 //! \brief Gets data from the given column by name of the current rowset. 1043 //! 1044 //! \param column_name column's name. 1045 //! \throws database_error, index_range_error, type_incompatible_error, null_access_error 1046 template<class T> 1047 T get(const string_type& column_name) const; 1048 1049 //! \brief Gets data from the given column by name of the current rowset. 1050 //! If the data is null, fallback is returned instead. 1051 //! 1052 //! \param column_name column's name. 1053 //! \param fallback if value is null, return fallback instead. 1054 //! \throws database_error, index_range_error, type_incompatible_error 1055 template<class T> 1056 T get(const string_type& column_name, const T& fallback) const; 1057 1058 //! \brief Returns true if and only if the given column of the current rowset is null. 1059 //! 1060 //! There is a bug/limitation in ODBC drivers for SQL Server (and possibly others) 1061 //! which causes SQLBindCol() to never write SQL_NOT_NULL to the length/indicator 1062 //! buffer unless you also bind the data column. Nanodbc's is_null() will return 1063 //! correct values for (n)varchar(max) columns when you ensure that SQLGetData() 1064 //! has been called for that column (i.e. after get() or get_ref() is called). 1065 //! 1066 //! Columns are numbered from left to right and 0-indexed. 1067 //! \see get(), get_ref() 1068 //! \param column position. 1069 //! \throws database_error, index_range_error 1070 bool is_null(short column) const; 1071 1072 //! \brief Returns true if and only if the given column by name of the current rowset is null. 1073 //! 1074 //! See is_null(short column) for details on a bug/limitation of some ODBC drivers. 1075 //! \see is_null() 1076 //! \param column_name column's name. 1077 //! \throws database_error, index_range_error 1078 bool is_null(const string_type& column_name) const; 1079 1080 //! \brief Returns the name of the specified column. 1081 //! 1082 //! Columns are numbered from left to right and 0-indexed. 1083 //! \param column position. 1084 //! \throws index_range_error 1085 string_type column_name(short column) const; 1086 1087 //! \brief Returns the size of the specified column. 1088 //! 1089 //! Columns are numbered from left to right and 0-indexed. 1090 //! \param column position. 1091 //! \throws index_range_error 1092 long column_size(short column) const; 1093 1094 //! \brief Returns the column number of the specified column name. 1095 //! 1096 //! Columns are numbered from left to right and 0-indexed. 1097 //! \param column_name column's name. 1098 //! \throws index_range_error 1099 short column(const string_type& column_name) const; 1100 1101 //! Returns a identifying integer value representing the SQL type of this column. 1102 int column_datatype(short column) const; 1103 1104 //! Returns a identifying integer value representing the SQL type of this column by name. 1105 int column_datatype(const string_type& column_name) const; 1106 1107 //! Returns a identifying integer value representing the C type of this column. 1108 int column_c_datatype(short column) const; 1109 1110 //! Returns a identifying integer value representing the C type of this column by name. 1111 int column_c_datatype(const string_type& column_name) const; 1112 1113 //! Returns the next result, for example when stored procedure returns multiple result sets. 1114 bool next_result(); 1115 1116 //! If and only if result object is valid, returns true. 1117 explicit operator bool() const; 1118 1119 private: 1120 result(statement statement, long rowset_size); 1121 1122 private: 1123 class result_impl; 1124 friend class nanodbc::statement::statement_impl; 1125 friend class nanodbc::catalog; 1126 1127 private: 1128 std::shared_ptr<result_impl> impl_; 1129 }; 1130 1131 1132 // 1133 // .d8888b. 888 888 1134 // d88P Y88b 888 888 1135 // 888 888 888 888 1136 // 888 8888b. 888888 8888b. 888 .d88b. .d88b. 1137 // 888 "88b 888 "88b 888 d88""88b d88P"88b 1138 // 888 888 .d888888 888 .d888888 888 888 888 888 888 1139 // Y88b d88P 888 888 Y88b. 888 888 888 Y88..88P Y88b 888 1140 // "Y8888P" "Y888888 "Y888 "Y888888 888 "Y88P" "Y88888 1141 // 888 1142 // Y8b d88P 1143 // "Y88P" 1144 // MARK: Catalog - 1145 1146 class catalog 1147 { 1148 public: 1149 1150 class tables 1151 { 1152 public: 1153 bool next(); 1154 string_type table_catalog() const; 1155 string_type table_schema() const; 1156 string_type table_name() const; 1157 string_type table_type() const; 1158 string_type table_remarks() const; 1159 1160 private: 1161 friend class nanodbc::catalog; 1162 tables(result& find_result); 1163 result result_; 1164 }; 1165 1166 class columns 1167 { 1168 public: 1169 1170 //! \brief 1171 bool next(); 1172 1173 //! \brief 1174 string_type table_catalog() const; 1175 1176 //! \brief 1177 string_type table_schema() const; 1178 1179 //! \brief 1180 string_type table_name() const; 1181 1182 //! \brief 1183 string_type column_name() const; 1184 1185 //! \brief 1186 short data_type() const; 1187 1188 //! \brief 1189 string_type type_name() const; 1190 1191 //! \brief 1192 long column_size() const; 1193 1194 //! \brief 1195 long buffer_length() const; 1196 1197 //! \brief 1198 short decimal_digits() const; 1199 1200 //! \brief 1201 short numeric_precision_radix() const; 1202 1203 //! \brief 1204 short nullable() const; 1205 1206 //! \brief 1207 string_type remarks() const; 1208 1209 //! \brief 1210 string_type column_default() const; 1211 1212 //! \brief 1213 short sql_data_type() const; 1214 1215 //! \brief 1216 short sql_datetime_subtype() const; 1217 1218 //! \brief 1219 long char_octed_length() const; 1220 1221 //! \brief Ordinal position of the column in the table. 1222 //! The first column in the table is number 1. 1223 //! Returns ORDINAL_POSITION column value in result set returned by SQLColumns. 1224 long ordinal_position() const; 1225 1226 string_type is_nullable() const; 1227 1228 private: 1229 friend class nanodbc::catalog; 1230 columns(result& find_result); 1231 result result_; 1232 }; 1233 1234 class primary_keys 1235 { 1236 public: 1237 bool next(); 1238 string_type table_catalog() const; 1239 string_type table_schema() const; 1240 string_type table_name() const; 1241 string_type column_name() const; 1242 1243 //! \brief Column sequence number in the key (starting with 1). 1244 //! Returns valye of KEY_SEQ column in result set returned by SQLPrimaryKeys. 1245 short column_number() const; 1246 1247 //! \brief Primary key name. 1248 //! NULL if not applicable to the data source. 1249 //! Returns valye of PK_NAME column in result set returned by SQLPrimaryKeys. 1250 string_type primary_key_name() const; 1251 1252 private: 1253 friend class nanodbc::catalog; 1254 primary_keys(result& find_result); 1255 result result_; 1256 }; 1257 1258 //! \brief Creates catalog operating on database accessible through the specified connection. 1259 catalog(connection& conn); 1260 1261 //! \brief Creates result set with tables information. 1262 //! 1263 //! Tables information is obtained by executing SQLTable function within 1264 //! scope of the connected database accessible with the specified connection. 1265 //! Since this function is implemented in terms of the SQLTables, it returns 1266 //! result set ordered by TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, and TABLE_NAME. 1267 catalog::tables find_tables( 1268 const string_type& table = string_type() 1269 , const string_type& type = string_type() 1270 , const string_type& schema = string_type() 1271 , const string_type& catalog = string_type()); 1272 1273 //! \brief Creates result set with columns information in specified tables. 1274 //! 1275 //! Columns information is obtained by executing SQLColumns function within 1276 //! scope of the connected database accessible with the specified connection. 1277 //! Since this function is implemented in terms of the SQLColumns, it returns 1278 //! result set ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and ORDINAL_POSITION. 1279 catalog::columns find_columns( 1280 const string_type& column = string_type() 1281 , const string_type& table = string_type() 1282 , const string_type& schema = string_type() 1283 , const string_type& catalog = string_type()); 1284 1285 //! \brief Creates result set with primary key information. 1286 //! 1287 //! Returns result set with column names that make up the primary key for a table. 1288 //! The primary key information is obtained by executing SQLPrimaryKey function within 1289 //! scope of the connected database accessible with the specified connection. 1290 catalog::primary_keys find_primary_keys( 1291 const string_type& table 1292 , const string_type& schema = string_type() 1293 , const string_type& catalog = string_type()); 1294 1295 private: 1296 connection conn_; 1297 }; 1298 1299 //! @} 1300 1301 // 8888888888 8888888888 888 d8b 1302 // 888 888 888 Y8P 1303 // 888 888 888 1304 // 8888888 888d888 .d88b. .d88b. 8888888 888 888 88888b. .d8888b 888888 888 .d88b. 88888b. .d8888b 1305 // 888 888P" d8P Y8b d8P Y8b 888 888 888 888 "88b d88P" 888 888 d88""88b 888 "88b 88K 1306 // 888 888 88888888 88888888 888 888 888 888 888 888 888 888 888 888 888 888 "Y8888b. 1307 // 888 888 Y8b. Y8b. 888 Y88b 888 888 888 Y88b. Y88b. 888 Y88..88P 888 888 X88 1308 // 888 888 "Y8888 "Y8888 888 "Y88888 888 888 "Y8888P "Y888 888 "Y88P" 888 888 88888P' 1309 // MARK: Free Functions - 1310 1311 //! \addtogroup mainf Free Functions 1312 //! \brief Convenience functions. 1313 //! 1314 //! @{ 1315 1316 //! \brief Immediately opens, prepares, and executes the given query directly on the given connection. 1317 //! \param conn The connection where the statement will be executed. 1318 //! \param query The SQL query that will be executed. 1319 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 1320 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 1321 //! \return A result set object. 1322 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 1323 //! \see open(), prepare(), execute(), result, transaction 1324 result execute( 1325 connection& conn 1326 , const string_type& query 1327 , long batch_operations = 1 1328 , long timeout = 0); 1329 1330 //! \brief Immediately opens, prepares, and executes the given query directly on the given connection without creating result object. 1331 //! \param conn The connection where the statement will be executed. 1332 //! \param query The SQL query that will be executed. 1333 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 1334 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 1335 //! \return A result set object. 1336 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 1337 //! \see open(), prepare(), execute(), result, transaction 1338 void just_execute( 1339 connection& conn 1340 , const string_type& query 1341 , long batch_operations = 1 1342 , long timeout = 0); 1343 1344 //! \brief Execute the previously prepared query now. 1345 //! \param stmt The prepared statement that will be executed. 1346 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 1347 //! \throws database_error 1348 //! \return A result set object. 1349 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 1350 //! \see open(), prepare(), execute(), result 1351 result execute(statement& stmt, long batch_operations = 1); 1352 1353 //! \brief Execute the previously prepared query now and without creating result object. 1354 //! \param stmt The prepared statement that will be executed. 1355 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 1356 //! \throws database_error 1357 //! \return A result set object. 1358 //! \attention You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed. 1359 //! \see open(), prepare(), execute(), result 1360 void just_execute(statement& stmt, long batch_operations = 1); 1361 1362 //! \brief Execute the previously prepared query now. 1363 //! Executes within the context of a transaction object and commits the transaction directly after execution. 1364 //! \param stmt The prepared statement that will be executed in batch. 1365 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 1366 //! \throws database_error 1367 //! \return A result set object. 1368 //! \see open(), prepare(), execute(), result, transaction 1369 result transact(statement& stmt, long batch_operations); 1370 1371 //! \brief Execute the previously prepared query now and without creating result object. 1372 //! Executes within the context of a transaction object and commits the transaction directly after execution. 1373 //! \param stmt The prepared statement that will be executed in batch. 1374 //! \param batch_operations Numbers of rows to fetch per rowset, or the number of batch parameters to process. 1375 //! \throws database_error 1376 //! \return A result set object. 1377 //! \see open(), prepare(), execute(), result, transaction 1378 void just_transact(statement& stmt, long batch_operations); 1379 1380 //! \brief Prepares the given statement to execute on it associated connection. 1381 //! If the statement is not open throws programming_error. 1382 //! \param stmt The prepared statement that will be executed in batch. 1383 //! \param query The SQL query that will be executed. 1384 //! \param timeout The number in seconds before query timeout. Default is 0 indicating no timeout. 1385 //! \see open() 1386 //! \throws database_error, programming_error 1387 void prepare(statement& stmt, const string_type& query, long timeout = 0); 1388 1389 //! @} 1390 1391 } // namespace nanodbc 1392 1393 #endif // NANODBC_H 1394 1395 #endif // _ODBC 1396 1397 #endif // DOXYGEN_SHOULD_SKIP_THIS 1398