docs/latex/wx/db.tex

   1 \section{\class{wxDb}}\label{wxdb}
   2
   3 A wxDb instance is a connection to an ODBC datasource which may
   4 be opened, closed, and re-opened an unlimited number of times.  A
   5 database connection allows function to be performed directly on the
   6 datasource, as well as allowing access to any tables/views defined in
   7 the datasource to which the user has sufficient privileges.
   8
   9 See the \helpref{database classes overview}{odbcoverview} for
  10 an introduction to using the ODBC classes.
  11
  12 \wxheading{Include files}
  13
  14 <wx/db.h>
  15
  16 \wxheading{Library}
  17
  18 \helpref{wxOdbc}{librarieslist}
  19
  20 \wxheading{Helper classes and data structures}
  21
  22 The following classes and structs are defined in db.cpp/.h for use with the wxDb class.
  23
  24 \begin{itemize}\itemsep=0pt
  25 \item \helpref{wxDbColFor}{wxdbcolfor}
  26 \item \helpref{wxDbColInf}{wxdbcolinf}
  27 \item \helpref{wxDbTableInf}{wxdbtableinf}
  28 \item \helpref{wxDbInf}{wxdbinf}
  29 \end{itemize}
  30
  31 \wxheading{Constants}
  32
  33 NOTE: In a future release, all ODBC class constants will be prefaced with 'wx'.
  34
  35 \begin{verbatim}
  36     wxDB_PATH_MAX           Maximum path length allowed to be passed to
  37                             the ODBC driver to indicate where the data
  38                             file(s) are located.
  39
  40     DB_MAX_COLUMN_NAME_LEN  Maximum supported length for the name of a
  41                             column
  42
  43     DB_MAX_ERROR_HISTORY    Maximum number of error messages retained in
  44                             the queue before being overwritten by new
  45                             errors.
  46
  47     DB_MAX_ERROR_MSG_LEN    Maximum supported length of an error message
  48                             returned by the ODBC classes
  49
  50     DB_MAX_STATEMENT_LEN    Maximum supported length for a complete SQL
  51                             statement to be passed to the ODBC driver
  52
  53     DB_MAX_TABLE_NAME_LEN   Maximum supported length for the name of a
  54                             table
  55
  56     DB_MAX_WHERE_CLAUSE_LEN Maximum supported WHERE clause length that
  57                             can be passed to the ODBC driver
  58
  59     DB_TYPE_NAME_LEN        Maximum length of the name of a column's
  60                             data type
  61 \end{verbatim}
  62
  63 \subsection{Enumerated types}\label{wxdbenumeratedtypes}
  64
  65 \wxheading{Enumerated types}
  66
  67 \docparam{enum {\bf wxDbSqlLogState}}{sqlLogOFF, sqlLogON}
  68
  69 {\it enum {\bf wxDBMS}}
  70
  71 These are the databases currently tested and working with the ODBC classes.  A call to \helpref{wxDb::Dbms}{wxdbdbms} will return one of these enumerated values listed below.
  72
  73 \begin{itemize}\itemsep=0pt
  74 \item DB2
  75 \item DBase (IV, V)**
  76 \item Firebird
  77 \item INFORMIX
  78 \item Interbase
  79 \item MS SQL Server (v7 - minimal testing)
  80 \item MS Access (97, 2000, 2002, and 2003)
  81 \item MySQL (2.x and 3.5 - use the 2.5x drivers though)
  82 \item Oracle (v7, v8, v8i)
  83 \item Pervasive SQL
  84 \item PostgreSQL
  85 \item Sybase (ASA and ASE)
  86 \item XBase Sequiter
  87 \item VIRTUOSO
  88 \end{itemize}
  89
  90 See the remarks in \helpref{wxDb::Dbms}{wxdbdbms} for exceptions/issues with each of these database engines.
  91
  92 \wxheading{Public member variables}
  93
  94 \docparam{SWORD {\bf wxDb::cbErrorMsg}}{This member variable is populated as a result of calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}.  Contains the count of bytes in the wxDb::errorMsg string.}
  95
  96 \docparam{int {\bf wxDb::DB\_STATUS}}{The last ODBC error/status that occurred on this data connection.  Possible codes are:}
  97
  98 \begin{verbatim}
  99    DB_ERR_GENERAL_WARNING                     // SqlState = '01000'
 100    DB_ERR_DISCONNECT_ERROR                    // SqlState = '01002'
 101    DB_ERR_DATA_TRUNCATED                      // SqlState = '01004'
 102    DB_ERR_PRIV_NOT_REVOKED                    // SqlState = '01006'
 103    DB_ERR_INVALID_CONN_STR_ATTR               // SqlState = '01S00'
 104    DB_ERR_ERROR_IN_ROW                        // SqlState = '01S01'
 105    DB_ERR_OPTION_VALUE_CHANGED                // SqlState = '01S02'
 106    DB_ERR_NO_ROWS_UPD_OR_DEL                  // SqlState = '01S03'
 107    DB_ERR_MULTI_ROWS_UPD_OR_DEL               // SqlState = '01S04'
 108    DB_ERR_WRONG_NO_OF_PARAMS                  // SqlState = '07001'
 109    DB_ERR_DATA_TYPE_ATTR_VIOL                 // SqlState = '07006'
 110    DB_ERR_UNABLE_TO_CONNECT                   // SqlState = '08001'
 111    DB_ERR_CONNECTION_IN_USE                   // SqlState = '08002'
 112    DB_ERR_CONNECTION_NOT_OPEN                 // SqlState = '08003'
 113    DB_ERR_REJECTED_CONNECTION                 // SqlState = '08004'
 114    DB_ERR_CONN_FAIL_IN_TRANS                  // SqlState = '08007'
 115    DB_ERR_COMM_LINK_FAILURE                   // SqlState = '08S01'
 116    DB_ERR_INSERT_VALUE_LIST_MISMATCH          // SqlState = '21S01'
 117    DB_ERR_DERIVED_TABLE_MISMATCH              // SqlState = '21S02'
 118    DB_ERR_STRING_RIGHT_TRUNC                  // SqlState = '22001'
 119    DB_ERR_NUMERIC_VALUE_OUT_OF_RNG            // SqlState = '22003'
 120    DB_ERR_ERROR_IN_ASSIGNMENT                 // SqlState = '22005'
 121    DB_ERR_DATETIME_FLD_OVERFLOW               // SqlState = '22008'
 122    DB_ERR_DIVIDE_BY_ZERO                      // SqlState = '22012'
 123    DB_ERR_STR_DATA_LENGTH_MISMATCH            // SqlState = '22026'
 124    DB_ERR_INTEGRITY_CONSTRAINT_VIOL           // SqlState = '23000'
 125    DB_ERR_INVALID_CURSOR_STATE                // SqlState = '24000'
 126    DB_ERR_INVALID_TRANS_STATE                 // SqlState = '25000'
 127    DB_ERR_INVALID_AUTH_SPEC                   // SqlState = '28000'
 128    DB_ERR_INVALID_CURSOR_NAME                 // SqlState = '34000'
 129    DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL         // SqlState = '37000'
 130    DB_ERR_DUPLICATE_CURSOR_NAME               // SqlState = '3C000'
 131    DB_ERR_SERIALIZATION_FAILURE               // SqlState = '40001'
 132    DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL2        // SqlState = '42000'
 133    DB_ERR_OPERATION_ABORTED                   // SqlState = '70100'
 134    DB_ERR_UNSUPPORTED_FUNCTION                // SqlState = 'IM001'
 135    DB_ERR_NO_DATA_SOURCE                      // SqlState = 'IM002'
 136    DB_ERR_DRIVER_LOAD_ERROR                   // SqlState = 'IM003'
 137    DB_ERR_SQLALLOCENV_FAILED                  // SqlState = 'IM004'
 138    DB_ERR_SQLALLOCCONNECT_FAILED              // SqlState = 'IM005'
 139    DB_ERR_SQLSETCONNECTOPTION_FAILED          // SqlState = 'IM006'
 140    DB_ERR_NO_DATA_SOURCE_DLG_PROHIB           // SqlState = 'IM007'
 141    DB_ERR_DIALOG_FAILED                       // SqlState = 'IM008'
 142    DB_ERR_UNABLE_TO_LOAD_TRANSLATION_DLL      // SqlState = 'IM009'
 143    DB_ERR_DATA_SOURCE_NAME_TOO_LONG           // SqlState = 'IM010'
 144    DB_ERR_DRIVER_NAME_TOO_LONG                // SqlState = 'IM011'
 145    DB_ERR_DRIVER_KEYWORD_SYNTAX_ERROR         // SqlState = 'IM012'
 146    DB_ERR_TRACE_FILE_ERROR                    // SqlState = 'IM013'
 147    DB_ERR_TABLE_OR_VIEW_ALREADY_EXISTS        // SqlState = 'S0001'
 148    DB_ERR_TABLE_NOT_FOUND                     // SqlState = 'S0002'
 149    DB_ERR_INDEX_ALREADY_EXISTS                // SqlState = 'S0011'
 150    DB_ERR_INDEX_NOT_FOUND                     // SqlState = 'S0012'
 151    DB_ERR_COLUMN_ALREADY_EXISTS               // SqlState = 'S0021'
 152    DB_ERR_COLUMN_NOT_FOUND                    // SqlState = 'S0022'
 153    DB_ERR_NO_DEFAULT_FOR_COLUMN               // SqlState = 'S0023'
 154    DB_ERR_GENERAL_ERROR                       // SqlState = 'S1000'
 155    DB_ERR_MEMORY_ALLOCATION_FAILURE           // SqlState = 'S1001'
 156    DB_ERR_INVALID_COLUMN_NUMBER               // SqlState = 'S1002'
 157    DB_ERR_PROGRAM_TYPE_OUT_OF_RANGE           // SqlState = 'S1003'
 158    DB_ERR_SQL_DATA_TYPE_OUT_OF_RANGE          // SqlState = 'S1004'
 159    DB_ERR_OPERATION_CANCELLED                 // SqlState = 'S1008'
 160    DB_ERR_INVALID_ARGUMENT_VALUE              // SqlState = 'S1009'
 161    DB_ERR_FUNCTION_SEQUENCE_ERROR             // SqlState = 'S1010'
 162    DB_ERR_OPERATION_INVALID_AT_THIS_TIME      // SqlState = 'S1011'
 163    DB_ERR_INVALID_TRANS_OPERATION_CODE        // SqlState = 'S1012'
 164    DB_ERR_NO_CURSOR_NAME_AVAIL                // SqlState = 'S1015'
 165    DB_ERR_INVALID_STR_OR_BUF_LEN              // SqlState = 'S1090'
 166    DB_ERR_DESCRIPTOR_TYPE_OUT_OF_RANGE        // SqlState = 'S1091'
 167    DB_ERR_OPTION_TYPE_OUT_OF_RANGE            // SqlState = 'S1092'
 168    DB_ERR_INVALID_PARAM_NO                    // SqlState = 'S1093'
 169    DB_ERR_INVALID_SCALE_VALUE                 // SqlState = 'S1094'
 170    DB_ERR_FUNCTION_TYPE_OUT_OF_RANGE          // SqlState = 'S1095'
 171    DB_ERR_INF_TYPE_OUT_OF_RANGE               // SqlState = 'S1096'
 172    DB_ERR_COLUMN_TYPE_OUT_OF_RANGE            // SqlState = 'S1097'
 173    DB_ERR_SCOPE_TYPE_OUT_OF_RANGE             // SqlState = 'S1098'
 174    DB_ERR_NULLABLE_TYPE_OUT_OF_RANGE          // SqlState = 'S1099'
 175    DB_ERR_UNIQUENESS_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1100'
 176    DB_ERR_ACCURACY_OPTION_TYPE_OUT_OF_RANGE   // SqlState = 'S1101'
 177    DB_ERR_DIRECTION_OPTION_OUT_OF_RANGE       // SqlState = 'S1103'
 178    DB_ERR_INVALID_PRECISION_VALUE             // SqlState = 'S1104'
 179    DB_ERR_INVALID_PARAM_TYPE                  // SqlState = 'S1105'
 180    DB_ERR_FETCH_TYPE_OUT_OF_RANGE             // SqlState = 'S1106'
 181    DB_ERR_ROW_VALUE_OUT_OF_RANGE              // SqlState = 'S1107'
 182    DB_ERR_CONCURRENCY_OPTION_OUT_OF_RANGE     // SqlState = 'S1108'
 183    DB_ERR_INVALID_CURSOR_POSITION             // SqlState = 'S1109'
 184    DB_ERR_INVALID_DRIVER_COMPLETION           // SqlState = 'S1110'
 185    DB_ERR_INVALID_BOOKMARK_VALUE              // SqlState = 'S1111'
 186    DB_ERR_DRIVER_NOT_CAPABLE                  // SqlState = 'S1C00'
 187    DB_ERR_TIMEOUT_EXPIRED                     // SqlState = 'S1T00'
 188 \end{verbatim}
 189
 190 \docparam{struct {\bf wxDb::dbInf}}{This structure is internal to the
 191 wxDb class and contains details of the ODBC datasource that the current
 192 instance of the wxDb is connected to in its members.  When the datasource
 193 is opened, all of the information contained in the dbInf structure is
 194 queried from the datasource.  This information is used almost exclusively
 195 within the ODBC class library.  Where there may be a need for particular
 196 portions of this information outside of the class library, member
 197 functions (e.g.
 198 \helpref{wxDbTable::IsCursorClosedOnCommit}{wxdbtableiscursorclosedoncommit})
 199 have been added for ease of use.}
 200
 201 \begin{verbatim}
 202    wxChar dbmsName[40]        - Name of the dbms product
 203    wxChar dbmsVer[64]         - Version # of the dbms product
 204    wxChar driverName[40]      - Driver name
 205    wxChar odbcVer[60]         - ODBC version of the driver
 206    wxChar drvMgrOdbcVer[60]   - ODBC version of the driver manager
 207    wxChar driverVer[60]       - Driver version
 208    wxChar serverName[80]      - Server Name, typically a connect string
 209    wxChar databaseName[128]   - Database filename
 210    wxChar outerJoins[2]       - Does datasource support outer joins
 211    wxChar procedureSupport[2] - Does datasource support stored
 212                                 procedures
 213    UWORD  maxConnections      - Maximum # of connections datasource
 214                                 supports
 215    UWORD  maxStmts            - Maximum # of HSTMTs per HDBC
 216    UWORD  apiConfLvl          - ODBC API conformance level
 217    UWORD  cliConfLvl          - Is datasource SAG compliant
 218    UWORD  sqlConfLvl          - SQL conformance level
 219    UWORD  cursorCommitBehavior   - How cursors are affected on db commit
 220    UWORD  cursorRollbackBehavior - How cursors are affected on db
 221                                    rollback
 222    UWORD  supportNotNullClause   - Does datasource support NOT NULL
 223                                    clause
 224    wxChar supportIEF[2]       - Integrity Enhancement Facility (Ref.
 225                                 Integrity)
 226    UDWORD txnIsolation        - Transaction isolation level supported by
 227                                 driver
 228    UDWORD txnIsolationOptions - Transaction isolation level options
 229                                 available
 230    UDWORD fetchDirections     - Fetch directions supported
 231    UDWORD lockTypes           - Lock types supported in SQLSetPos
 232    UDWORD posOperations       - Position operations supported in
 233                                 SQLSetPos
 234    UDWORD posStmts            - Position statements supported
 235    UDWORD scrollConcurrency   - Scrollable cursor concurrency options
 236                                 supported
 237    UDWORD scrollOptions       - Scrollable cursor options supported
 238    UDWORD staticSensitivity   - Can additions/deletions/updates be
 239                                 detected
 240    UWORD  txnCapable          - Indicates if datasource supports
 241                                 transactions
 242    UDWORD loginTimeout        - Number seconds to wait for a login
 243                                 request
 244 \end{verbatim}
 245
 246 \docparam{wxChar {\bf wxDb::errorList}[DB\_MAX\_ERROR\_HISTORY][DB\_MAX\_ERROR\_MSG\_LEN]}{The last n ODBC errors that have occurred on this database connection.}
 247
 248 \docparam{wxChar {\bf wxDb::errorMsg}[SQL\_MAX\_MESSAGE\_LENGTH]}{This member variable is populated as a result of calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}.  It contains the ODBC error message text.}
 249
 250 \docparam{SDWORD {\bf wxDb::nativeError}}{Set by wxDb::DispAllErrors,
 251 wxDb::GetNextError, and wxDb::DispNextError.  It contains the
 252 datasource-specific error code returned by the datasource to the ODBC driver.
 253 Used for reporting ODBC errors.}
 254
 255 \docparam{wxChar {\bf wxDb::sqlState}[20]}{Set by wxDb::TranslateSqlState().
 256 Indicates the error state after a failed ODBC operation.  Used for reporting
 257 ODBC errors.}
 258
 259 \wxheading{Remarks}
 260
 261 Default cursor scrolling is defined by wxODBC\_FWD\_ONLY\_CURSORS in setup.h
 262 when the wxWidgets library is built.  This behavior can be overridden when
 263 an instance of a wxDb is created (see \helpref{wxDb constructor}{wxdbctor}).
 264 Default setting of this value true, as not all databases/drivers support
 265 both types of cursors.
 266
 267 \wxheading{See also}
 268
 269 \helpref{wxDbColFor}{wxdbcolfor}, \helpref{wxDbColInf}{wxdbcolinf},
 270 \helpref{wxDbTable}{wxdbtable}, \helpref{wxDbTableInf}{wxdbtableinf},
 271 \helpref{wxDbInf}{wxdbinf}
 272
 273 \subsection{Associated non-class functions}\label{wxdbfunctions}
 274
 275 The following functions are used in conjunction with the wxDb class.
 276
 277 \func{void}{wxDbCloseConnections}{\void}
 278
 279 \wxheading{Remarks}
 280
 281 Closes all cached connections that have been made through use of the
 282 \helpref{wxDbGetConnection}{wxdbfunctions} function.
 283
 284 NOTE: These connections are closed regardless of whether they are in use
 285 or not.  This function should only be called after the program has
 286 finished using the connections and all wxDbTable instances that use any of
 287 the connections have been closed.
 288
 289 This function performs a \helpref{wxDb::CommitTrans}{wxdbcommittrans}
 290 on the connection before closing it to commit any changes that are still
 291 pending, as well as to avoid any function sequence errors upon closing
 292 each connection.
 293
 294
 295 \func{int }{wxDbConnectionsInUse}{\void}
 296
 297 \wxheading{Remarks}
 298
 299 Returns a count of how many database connections are currently free ( not
 300 being used) that have been cached through use of the \helpref{wxDbGetConnection}{wxdbfunctions}
 301 function.
 302
 303
 304 \func{bool}{wxDbFreeConnection}{\param{wxDb *}{pDb}}
 305
 306 \wxheading{Remarks}
 307
 308 Searches the list of cached database connections connection for one matching
 309 the passed in wxDb instance.  If found, that cached connection is freed.
 310
 311 Freeing a connection means that it is marked as available (free) in the
 312 cache of connections, so that a call to \helpref{wxDbGetConnection}{wxdbfunctions}
 313 is able to return a pointer to the wxDb instance for use.  Freeing a
 314 connection does NOT close the connection, it only makes the connection
 315 available again.
 316
 317
 318 \func{wxDb *}{wxDbGetConnection}{\param{wxDbConnectInf *}{pDbConfig},
 319 \param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}
 320
 321 \wxheading{Remarks}
 322
 323 This function is used to request a "new" wxDb instance for use by the program.
 324 The wxDb instance returned is also opened (see \helpref{wxDb::Open}{wxdbopen}).
 325
 326 This function (along with wxDbFreeConnection() and wxDbCloseConnection())
 327 maintain a cache of wxDb instances for user/re-use by a program.  When a
 328 program needs a wxDb instance, it may call this function to obtain a wxDb
 329 instance.  If there is a wxDb instance in the cache that is currently unused
 330 that matches the connection requirements specified in {\it'pDbConfig'} then
 331 that cached connection is marked as no longer being free, and a pointer to
 332 the wxDb instance is returned.
 333
 334 If there are no connections available in the cache that meet the requirements
 335 given in {\it'pDbConfig'}, then a new wxDb instance is created to connect
 336 to the datasource specified in {\it'pDbConfig'} using the userID and password
 337 given in {\it'pDbConfig'}.
 338
 339 NOTE: The caching routine also uses the \helpref{wxDb::Open}{wxdbopen}
 340 connection datatype copying code.  If the call to wxDbGetConnection()
 341 requests a connection to a datasource, and there is not one available in the
 342 cache, a new connection is created.  But when the connection is opened,
 343 instead of polling the datasource over again for its datatypes, if a
 344 connection to the same datasource (using the same userID/password) has already
 345 been done previously, the new connection skips querying the datasource for
 346 its datatypes, and uses the same datatypes determined previously by the
 347 other connection(s) for that same datasource.  This cuts down greatly on
 348 network traffic, database load, and connection creation time.
 349
 350 When the program is done using a connection created through a call to
 351 wxDbGetConnection(), the program should call wxDbFreeConnection() to release
 352 the wxDb instance back to the cache.  DO NOT DELETE THE wxDb INSTANCE!
 353 Deleting the wxDb instance returned can cause a crash/memory corruption
 354 later in the program when the cache is cleaned up.
 355
 356 When exiting the program, call wxDbCloseConnections() to close all the
 357 cached connections created by calls to wxDbGetConnection().
 358
 359
 360 \func{const wxChar *}{wxDbLogExtendedErrorMsg}{\param{const wxChar *}{userText}, \param{wxDb *}{pDb}, \param{wxChar *}{ErrFile}, \param{int }{ErrLine}}
 361
 362 Writes a message to the wxLog window (stdout usually) when an internal
 363 error situation occurs.
 364
 365 \func{bool}{wxDbSqlLog}{\param{wxDbSqlLogState }{state}, \param{const wxString \&}{filename = SQL\_LOG\_FILENAME}}
 366
 367 \wxheading{Remarks}
 368
 369 This function sets the sql log state for all open wxDb objects
 370
 371 \func{bool}{wxDbGetDataSource}{\param{HENV }{henv}, \param{wxChar *}{Dsn}, \param{SWORD }{DsnMax}, \param{wxChar *}{DsDesc}, \param{SWORD }{DsDescMax}, \param{UWORD }{direction = SQL\_FETCH\_NEXT}}
 372
 373 \wxheading{Remarks}
 374
 375 This routine queries the ODBC driver manager for a list of available
 376 datasources.  Repeatedly call this function to obtain all the datasources
 377 available through the ODBC driver manager on the current workstation.
 378
 379 \begin{verbatim}
 380     wxArrayString strArray;
 381
 382     while (wxDbGetDataSource(DbConnectInf.GetHenv(), Dsn, SQL_MAX_DSN_LENGTH+1, DsDesc, 255))
 383         strArray.Add(Dsn);
 384 \end{verbatim}
 385
 386 \latexignore{\rtfignore{\wxheading{Members}}}
 387
 388 \membersection{wxDb::wxDb}\label{wxdbctor}
 389
 390 \func{}{wxDb}{\void}
 391
 392 Default constructor.
 393
 394 \func{}{wxDb}{\param{const HENV \&}{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}
 395
 396 Constructor, used to create an ODBC connection to a datasource.
 397
 398 \wxheading{Parameters}
 399
 400 \docparam{aHenv}{Environment handle used for this connection.  See
 401 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv}}
 402
 403 \docparam{FwdOnlyCursors}{Will cursors created for use with this datasource
 404 connection only allow forward scrolling cursors.}
 405
 406 \wxheading{Remarks}
 407
 408 This is the constructor for the wxDb class.  The wxDb object must
 409 be created and opened before any database activity can occur.
 410
 411 \wxheading{Example}
 412
 413 \begin{verbatim}
 414    wxDbConnectInf ConnectInf;
 415    ....Set values for member variables of ConnectInf here
 416
 417    wxDb sampleDB(ConnectInf.GetHenv());
 418    if (!sampleDB.Open(ConnectInf.GetDsn(), ConnectInf.GetUserID(),
 419                            ConnectInf.GetPassword()))
 420    {
 421       // Error opening datasource
 422    }
 423 \end{verbatim}
 424
 425 \wxheading{See also}
 426
 427 \helpref{wxDbGetConnection}{wxdbfunctions}
 428
 429 \membersection{wxDb::Catalog}\label{wxdbcatalog}
 430
 431 \func{bool}{Catalog}{\param{wxChar *}{ userID}, \param{const wxString \&}{fileName =
 432 SQL\_CATALOG\_FILENAME}}
 433
 434 Allows a data "dictionary" of the datasource to be created, dumping pertinent
 435 information about all data tables to which the user specified in userID has
 436 access.
 437
 438 \wxheading{Parameters}
 439
 440 \docparam{userID}{Database user name to use in accessing the database.  All
 441 tables to which this user has rights will be evaluated in the catalog.}
 442
 443 \docparam{fileName}{{\it OPTIONAL}.  Name of the text file to create and write
 444 the DB catalog to.  Default is SQL\_CATALOG\_FILENAME.}
 445
 446 \wxheading{Return value}
 447
 448 Returns true if the catalog request was successful, or false if there was some
 449 reason that the catalog could not be generated.
 450
 451 \wxheading{Example}
 452
 453 \begin{verbatim}
 454 ============== ============== ================ ========= =======
 455 TABLE NAME     COLUMN NAME    DATA TYPE        PRECISION  LENGTH
 456 ============== ============== ================ ========= =======
 457 EMPLOYEE       RECID          (0008)NUMBER            15       8
 458 EMPLOYEE       USER_ID        (0012)VARCHAR2          13      13
 459 EMPLOYEE       FULL_NAME      (0012)VARCHAR2          26      26
 460 EMPLOYEE       PASSWORD       (0012)VARCHAR2          26      26
 461 EMPLOYEE       START_DATE     (0011)DATE              19      16
 462 \end{verbatim}
 463
 464
 465 \membersection{wxDb::Close}\label{wxdbclose}
 466
 467 \func{void}{Close}{\void}
 468
 469 Closes the database connection.
 470
 471 \wxheading{Remarks}
 472
 473 At the end of your program, when you have finished all of your database work,
 474 you must close the ODBC connection to the datasource.  There are actually
 475 four steps involved in doing this as illustrated in the example.
 476
 477 Any wxDbTable instances which use this connection must be deleted before
 478 closing the database connection.
 479
 480 \wxheading{Example}
 481
 482 \begin{verbatim}
 483    // Commit any open transactions on the datasource
 484    sampleDB.CommitTrans();
 485
 486    // Delete any remaining wxDbTable objects allocated with new
 487    delete parts;
 488
 489    // Close the wxDb connection when finished with it
 490    sampleDB.Close();
 491 \end{verbatim}
 492
 493
 494 \membersection{wxDb::CommitTrans}\label{wxdbcommittrans}
 495
 496 \func{bool}{CommitTrans}{\void}
 497
 498 Permanently "commits" changes (insertions/deletions/updates) to the database.
 499
 500 \wxheading{Return value}
 501
 502 Returns true if the commit was successful, or false if the commit failed.
 503
 504 \wxheading{Remarks}
 505
 506 Transactions begin implicitly as soon as you make a change to the database
 507 with an insert/update/delete, or any other direct SQL command that performs
 508 one of these operations against the datasource.
 509 At any time thereafter, to save the changes to disk permanently, "commit"
 510 them by calling this function.
 511
 512 Calling this member function commits ALL open transactions on this ODBC
 513 connection.  For example, if three different wxDbTable instances used the
 514 same connection to the datasource, committing changes made on one of those
 515 wxDbTable instances commits any pending transactions on all three wxDbTable
 516 instances.
 517
 518 Until a call to wxDb::CommitTrans() is made, no other user or cursor is able
 519 to see any changes made to the row(s) that have been inserted/modified/deleted.
 520
 521
 522 \wxheading{Special Note : {\it Cursors} }
 523
 524 \normalbox{It is important to understand that different database/ODBC driver
 525 combinations handle transactions differently.  One thing in particular that
 526 you must pay attention to is cursors, in regard to transactions.  Cursors are
 527 what allow you to scroll through records forward and backward and to
 528 manipulate records as you scroll through them.  When you issue a query, a
 529 cursor is created behind the scenes.  The cursor keeps track of the query and
 530 keeps track of the current record pointer.  After you commit or rollback a
 531 transaction, the cursor may be closed automatically.  This is database
 532 dependent, and with some databases this behavior can be controlled through
 533 management functions.  This means you would need to requery the datasource
 534 before you can perform any additional work using this cursor.  This is only
 535 necessary however if the datasource closes the cursor after a commit or
 536 rollback.  Use the
 537 \helpref{wxDbTable::IsCursorClosedOnCommit}{wxdbtableiscursorclosedoncommit}
 538 member function to determine the datasource's transaction behavior.  Note, in
 539 many situations it is very inefficient to assume the cursor is closed and
 540 always requery.  This could put a significant, unnecessary load on datasources
 541 that leave the cursors open after a transaction.}
 542
 543
 544 \membersection{wxDb::CreateView}\label{wxdbcreateviews}
 545
 546 \func{bool}{CreateView}{\param{const wxString \&}{ viewName},
 547 \param{const wxString \&}{ colList}, \param{const wxString \&}{pSqlStmt}}
 548
 549 Creates a SQL VIEW of one or more tables in a single datasource.  Note that
 550 this function will only work against databases which support views (currently
 551 only Oracle as of November 21 2000).
 552
 553 \wxheading{Parameters}
 554
 555 \docparam{viewName}{The name of the view.  e.g. PARTS\_V}
 556
 557 \docparam{colList}{{\it OPTIONAL} Pass in a comma delimited list of column
 558 names if you wish to explicitly name each column in the result set.  If not
 559 desired, pass in an empty string and the column names from the associated
 560 table(s) will be used.}
 561
 562 \docparam{pSqlStmt}{Pointer to the select statement portion of the CREATE
 563 VIEW statement.  Must be a complete, valid SQL SELECT statement.}
 564
 565 \wxheading{Remarks}
 566
 567 A 'view' is a logical table that derives columns from one or more other
 568 tables or views.  Once the view is created, it can be queried exactly like
 569 any other table in the database.
 570
 571 NOTE: Views are not available with all datasources.  Oracle is one example
 572 of a datasource which does support views.
 573
 574 \wxheading{Example}
 575
 576 \begin{verbatim}
 577    // Incomplete code sample
 578    db.CreateView("PARTS_SD1", "PN, PD, QTY",
 579                  "SELECT PART_NUM, PART_DESC, QTY_ON_HAND * 1.1 FROM PARTS \
 580                   WHERE STORAGE_DEVICE = 1");
 581
 582    // PARTS_SD1 can now be queried just as if it were a data table.
 583    // e.g. SELECT PN, PD, QTY FROM PARTS_SD1
 584 \end{verbatim}
 585
 586
 587 \membersection{wxDb::Dbms}\label{wxdbdbms}
 588
 589 \func{wxDBMS }{Dbms}{\void}
 590
 591 \wxheading{Remarks}
 592
 593 The return value will be of the enumerated type wxDBMS.  This enumerated
 594 type contains a list of all the currently tested and supported databases.
 595
 596 Additional databases may work with these classes, but the databases
 597 returned by this function have been tested and confirmed to work with
 598 these ODBC classes.
 599
 600 Possible values returned by this function can be viewed in the
 601 \helpref{Enumerated types}{wxdbenumeratedtypes} section of wxDb.
 602
 603 There are known issues with conformance to the ODBC standards with several
 604 datasources supported by the wxWidgets ODBC classes.  Please see the overview
 605 for specific details on which datasource have which issues.
 606
 607 \wxheading{Return value}
 608
 609 The return value will indicate which of the supported datasources is
 610 currently connected to by this connection.  In the event that the
 611 datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.
 612
 613
 614 \membersection{wxDb::DispAllErrors}\label{wxdbdispallerrors}
 615
 616 \func{bool}{DispAllErrors}{\param{HENV}{ aHenv}, \param{HDBC}{ aHdbc = SQL\_NULL\_HDBC}, \param{HSTMT}{ aHstmt = SQL\_NULL\_HSTMT}}
 617
 618 Used to log all database errors that occurred as a result of an executed
 619 database command.  This logging is automatic and also includes debug logging
 620 when compiled in debug mode via \helpref{wxLogDebug}{wxlogdebug}.  If logging
 621 is turned on via \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, then an
 622 entry is also logged to the defined log file.
 623
 624 \wxheading{Parameters}
 625
 626 \docparam{aHenv}{Handle to the ODBC environment.}
 627
 628 \docparam{aHdbc}{Handle to the ODBC connection.  Pass this in if the ODBC
 629 function call that erred required a hdbc or hstmt argument.}
 630
 631 \docparam{aHstmt}{Handle to the ODBC statement being executed against.  Pass
 632 this in if the ODBC function call that failed required a hstmt argument.}
 633
 634 \wxheading{Remarks}
 635
 636 This member function will log all of the ODBC error messages for the last
 637 ODBC function call that was made.  This function is normally used internally
 638 within the ODBC class library, but can be used programmatically after calling
 639 ODBC functions directly (i.e. SQLFreeEnv()).
 640
 641 \wxheading{Return value}
 642
 643 The function always returns false, so a call to this function can be made
 644 in the return statement of a code block in the event of a failure to
 645 perform an action (see the example below).
 646
 647 \wxheading{See also}
 648
 649 \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, wxDbSqlLog
 650
 651 \wxheading{Example}
 652
 653 \begin{verbatim}
 654    if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
 655       // Display all ODBC errors for this stmt
 656       return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
 657 \end{verbatim}
 658
 659 \membersection{wxDb::DispNextError}\label{wxdbdispnexterror}
 660
 661 \func{void}{DispNextError}{\void}
 662
 663 \wxheading{Remarks}
 664
 665 This function is normally used internally within the ODBC class library.
 666 It could be used programmatically after calling ODBC functions directly.  This
 667 function works in conjunction with \helpref{wxDb::GetNextError}{wxdbgetnexterror} when errors (or
 668 sometimes informational messages)  returned from ODBC need to be analyzed
 669 rather than simply displaying them as an error.  GetNextError() retrieves
 670 the next ODBC error from the ODBC error queue.  The wxDb member variables
 671 "sqlState", "nativeError" and "errorMsg" could then be evaluated.  To
 672 display the error retrieved, DispNextError() could then be called.
 673 The combination of GetNextError() and DispNextError() can be used to
 674 iteratively step through the errors returned from ODBC evaluating each
 675 one in context and displaying the ones you choose.
 676
 677 \wxheading{Example}
 678
 679 \begin{verbatim}
 680    // Drop the table before attempting to create it
 681    sprintf(sqlStmt, "DROP TABLE %s", tableName);
 682    // Execute the drop table statement
 683    if (SQLExecDirect(hstmt,(UCHAR FAR *)sqlStmt,SQL_NTS) != SQL_SUCCESS)
 684    {
 685       // Check for sqlState = S0002, "Table or view not found".
 686       // Ignore this error, bomb out on any other error.
 687       pDb->GetNextError(henv, hdbc, hstmt);
 688       if (wxStrcmp(pDb->sqlState, "S0002"))
 689       {
 690          pDb->DispNextError();   // Displayed error retrieved
 691          pDb->DispAllErrors(henv, hdbc, hstmt); // Display all other errors, if any
 692          pDb->RollbackTrans();   // Rollback the transaction
 693          CloseCursor();          // Close the cursor
 694          return(false);          // Return Failure
 695       }
 696    }
 697 \end{verbatim}
 698
 699
 700 \membersection{wxDb::DropView}\label{wxdbdropview}
 701
 702 \func{bool}{DropView}{\param{const wxString \&}{viewName}}
 703
 704 Drops the data table view named in 'viewName'.
 705
 706 \wxheading{Parameters}
 707
 708 \docparam{viewName}{Name of the view to be dropped.}
 709
 710 \wxheading{Remarks}
 711
 712 If the view does not exist, this function will return true.  Note that views are not supported with all datasources.
 713
 714 \membersection{wxDb::EscapeSqlChars}\label{wxdbescapesqlchars}
 715
 716 \func{wxString}{EscapeSqlChars}{\param{const wxString\& }{value}}
 717
 718 This function is used internally by wxWidgets while building SQL statements.
 719 It has been provided to help users who wish to explicity construct SQL
 720 statements to be sent to the server.  The function takes the value passed and
 721 returns it with any special characters escaped.  Which characters are
 722 considered special depends on what type of datasource the object is connected
 723 to.  For example, most database servers use a backslash as the escape
 724 character; if the value passed contains a backlash it will be replaced with a
 725 double backslash before it is passed to the server.  This function can be used
 726 to avoid passing statements with syntax errors to the server as well as prevent
 727 SQL injection attacks.
 728
 729 \wxheading{Parameters}
 730
 731 \docparam{value}{The value to be escaped.}
 732
 733 \membersection{wxDb::ExecSql}\label{wxdbexecsql}
 734
 735 \func{bool}{ExecSql}{\param{const wxString \&}{pSqlStmt}}
 736
 737 \func{bool}{ExecSql}{\param{const wxString \&}{pSqlStmt}, \param{wxDbColInf **}{columns}, \param{short \&}{numcols}}
 738
 739 Allows a native SQL command to be executed directly against the datasource.  In addition to being able to run any standard SQL command, use of this function allows a user to (potentially) utilize features specific to the datasource they are connected to that may not be available through ODBC.  The ODBC driver will pass the specified command directly to the datasource.
 740
 741 To get column amount and column names or other information about returned columns, pass {\it 'columns'} and {\it 'numcols'} parameters to the function also.
 742
 743 \wxheading{Parameters}
 744
 745 \docparam{pSqlStmt}{Pointer to the SQL statement to be executed.}
 746
 747 \docparam{columns}{On success, this function will set this pointer to point to array of \helpref{wxDbColInf}{wxdbcolinf} objects, holding information about columns returned by the query. You need to call delete[] for the pointer you pass here after you don't use it anymore to prevent memory leak.}
 748
 749 \docparam{numcols}{Reference to variable where amount of objects in {\it 'columns'}-parameter will be set.}
 750
 751 \wxheading{Remarks}
 752
 753 This member extends the wxDb class and allows you to build and execute ANY VALID
 754 SQL statement against the datasource.  This allows you to extend the class
 755 library by being able to issue any SQL statement that the datasource is capable
 756 of processing.
 757
 758 \wxheading{See also}
 759
 760 \helpref{wxDb::GetData}{wxdbgetdata}, \helpref{wxDb::GetNext}{wxdbgetnext}
 761
 762 \membersection{wxDb::FwdOnlyCursors}\label{wxdbfwdonlycursors}
 763
 764 \func{bool}{IsFwdOnlyCursors}{\void}
 765
 766 Older form (pre-2.3/2.4 of wxWidgets) of the
 767 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}.  This method is
 768 provided for backward compatibility only.  The method
 769 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors} should be
 770 used in place of this method.
 771
 772
 773 \func{wxDbInf *}{GetCatalog}{\param{const wxChar *}{userID}}
 774
 775 \membersection{wxDb::GetCatalog}\label{wxdbgetcatalog}
 776
 777 \func{wxDbInf *}{GetCatalog}{\param{const wxChar *}{userID}}
 778
 779 Returns a \helpref{wxDbInf}{wxdbinf} pointer that points to the catalog
 780 (datasource) name, schema, number of tables accessible to the current user,
 781 and a wxDbTableInf pointer to all data pertaining to all tables in the users
 782 catalog.
 783
 784 \wxheading{Parameters}
 785
 786 \docparam{userID}{Owner/Schema of the table.  Specify a userID when the datasource you are connected to allows multiple unique tables with the same name to be owned by different users.  {\it userID} is evaluated as follows:}
 787
 788 \begin{verbatim}
 789          userID == NULL  ... UserID is ignored (DEFAULT)
 790          userID == ""    ... UserID set equal to 'this->uid'
 791          userID != ""    ... UserID set equal to 'userID'
 792 \end{verbatim}
 793
 794 \wxheading{Remarks}
 795
 796 The returned catalog will only contain catalog entries for tables to which the user specified in 'userID' has sufficient privileges.  If no user is specified (NULL passed in), a catalog pertaining to all tables in the datasource accessible to the connected user (permissions apply) via this connection will be returned.
 797
 798 \membersection{wxDb::GetColumnCount}\label{wxdbgetcolumncount}
 799
 800 \func{int }{GetColumnCount}{\param{const wxString \&}{tableName}, \param{const wxChar *}{userID}}
 801
 802 \wxheading{Parameters}
 803
 804 \docparam{tableName}{The table name you wish to obtain column information about.}
 805
 806 \docparam{userID}{Name of the user that owns the table(s) (also referred to as schema).
 807 Required for some datasources for situations where there may be multiple tables with the
 808 same name in the datasource, but owned by different users. {\it userID } is
 809 evaluated in the following manner:}
 810
 811 \begin{verbatim}
 812          userID == NULL  ... UserID is ignored (DEFAULT)
 813          userID == ""    ... UserID set equal to 'this->uid'
 814          userID != ""    ... UserID set equal to 'userID'
 815 \end{verbatim}
 816
 817 \wxheading{Return value}
 818
 819 Returns a count of how many columns are in the specified table.  If an error
 820 occurs retrieving the number of columns, this function will return a -1.
 821
 822 \membersection{wxDb::GetColumns}\label{wxdbgetcolumns}
 823
 824 \func{wxDbColInf *}{GetColumns}{\param{const wxString \&}{tableName}, \param{UWORD *}{numCols}, \param{const wxChar *}{userID=NULL}}
 825
 826 \func{wxDbColInf *}{GetColumns}{\param{wxChar *}{tableName[]}, \param{const wxChar *}{userID}}
 827
 828 \wxheading{Parameters}
 829
 830 \docparam{tableName}{The table name you wish to obtain column information about.}
 831 \docparam{numCols}{Pointer to a UWORD which will hold a count of the number of columns returned by this function}
 832 \docparam{tableName[]}{An array of pointers to table names you wish to obtain column information about.  The last element of this array must be a NULL string.}
 833 \docparam{userID}{Name of the user that owns the table(s) (also referred to as schema).  Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. {\it userID} is evaluated in the following manner:}
 834
 835 \begin{verbatim}
 836          userID == NULL  ... UserID is ignored (DEFAULT)
 837          userID == ""    ... UserID set equal to 'this->uid'
 838          userID != ""    ... UserID set equal to 'userID'
 839 \end{verbatim}
 840
 841 \wxheading{Return value}
 842
 843 This function returns a pointer to an array of \helpref{wxDbColInf}{wxdbcolinf}
 844 structures, allowing you to obtain information regarding the columns of the
 845 named table(s).  If no columns were found, or an error occurred, this pointer
 846 will be NULL.
 847
 848 THE CALLING FUNCTION IS RESPONSIBLE FOR DELETING THE {\it wxDbColInf} MEMORY WHEN IT IS
 849 FINISHED WITH IT.
 850
 851 \normalbox{ALL column bindings associated with this wxDb instance are unbound
 852 by this function, including those used by any wxDbTable instances that use
 853 this wxDb instance.  This function should use its own wxDb instance
 854 to avoid undesired unbinding of columns.}
 855
 856 \wxheading{See also}
 857
 858 \helpref{wxDbColInf}{wxdbcolinf}
 859
 860 \wxheading{Example}
 861
 862 \begin{verbatim}
 863    wxChar *tableList[] = {"PARTS", 0};
 864    wxDbColInf *colInf = pDb->GetColumns(tableList);
 865    if (colInf)
 866    {
 867       // Use the column inf
 868       .......
 869       // Destroy the memory
 870       delete [] colInf;
 871    }
 872 \end{verbatim}
 873
 874 \membersection{wxDb::GetData}\label{wxdbgetdata}
 875
 876 \func{bool}{GetData}{\param{UWORD}{ colNumber}, \param{SWORD}{ cType},
 877 \param{PTR}{ pData}, \param{SDWORD}{ maxLen}, \param{SDWORD FAR *}{ cbReturned} }
 878
 879 Used to retrieve result set data without binding column values to memory
 880 variables (i.e. not using a wxDbTable instance to access table data).
 881
 882 \wxheading{Parameters}
 883
 884 \docparam{colNumber}{Ordinal number of the desired column in the result set to be
 885 returned.}
 886 \docparam{cType}{The C data type that is to be returned.  See a partial list
 887 in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}}
 888 \docparam{pData}{Memory buffer which will hold the data returned by the call
 889 to this function.}
 890 \docparam{maxLen}{Maximum size of the buffer {\it 'pData'} in characters.
 891 NOTE: Not UNICODE safe.  If this is a numeric field, a value of 0 may be
 892 passed for this parameter, as the API knows the size of the expected return
 893 value.}
 894 \docparam{cbReturned}{Pointer to the buffer containing the length of the
 895 actual data returned.  If this value comes back as SQL\_NULL\_DATA, then the
 896 \helpref{wxDb::GetData}{wxdbgetdata} call has failed.}
 897
 898 \wxheading{See also}
 899
 900 \helpref{wxDb::GetNext}{wxdbgetnext}, \helpref{wxDb::ExecSql}{wxdbexecsql}
 901
 902 \wxheading{Example}
 903
 904 \begin{verbatim}
 905     SDWORD cb;
 906     ULONG reqQty;
 907     wxString sqlStmt;
 908     sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
 909                  PART_RECID = 1450 AND REQUIRED_QTY > PICKED_QTY";
 910
 911     // Perform the query
 912     if (!pDb->ExecSql(sqlStmt.c_str()))
 913     {
 914         // ERROR
 915         return(0);
 916     }
 917
 918     // Request the first row of the result set
 919     if (!pDb->GetNext())
 920     {
 921         // ERROR
 922         return(0);
 923     }
 924
 925     // Read column #1 of the row returned by the call to ::GetNext()
 926     // and return the value in 'reqQty'
 927     if (!pDb->GetData(1, SQL_C_ULONG, &reqQty, 0, &cb))
 928     {
 929         // ERROR
 930         return(0);
 931     }
 932
 933     // Check for a NULL result
 934     if (cb == SQL_NULL_DATA)
 935         return(0);
 936 \end{verbatim}
 937
 938 \wxheading{Remarks}
 939
 940 When requesting multiple columns to be returned from the result set (for example, the SQL query
 941 requested 3 columns be returned), the calls to this function must request the columns in ordinal
 942 sequence (1,2,3 or 1,3 or 2,3).
 943
 944 \membersection{wxDb::GetDatabaseName}\label{wxdbgetdatabasename}
 945
 946 \func{const wxChar *}{GetDatabaseName}{\void}
 947
 948 Returns the name of the database engine.
 949
 950 \membersection{wxDb::GetDatasourceName}\label{wxdbgetdatasourcename}
 951
 952 \func{const wxString \&}{GetDatasourceName}{\void}
 953
 954 Returns the ODBC datasource name.
 955
 956 \membersection{wxDb::GetHDBC}\label{wxdbgethdbc}
 957
 958 \func{HDBC}{GetHDBC}{\void}
 959
 960 Returns the ODBC handle to the database connection.
 961
 962 \membersection{wxDb::GetHENV}\label{wxdbgethenv}
 963
 964 \func{HENV}{GetHENV}{\void}
 965
 966 Returns the ODBC environment handle.
 967
 968 \membersection{wxDb::GetHSTMT}\label{wxdbgethstmt}
 969
 970 \func{HSTMT}{GetHSTMT}{\void}
 971
 972 Returns the ODBC statement handle associated with this database connection.
 973
 974 \membersection{wxDb::GetKeyFields}\label{wxdbgetkeyfields}
 975
 976 \func{int }{GetKeyFields}{\param{const wxString \&}{tableName}, \param{wxDbColInf *}{colInf}, \param{UWORD }{numColumns}}
 977
 978 Used to determine which columns are members of primary or non-primary indexes on the specified table.  If a column is a member of a foreign key for some other table, that information is detected also.
 979
 980 This function is primarily for use by the \helpref{wxDb::GetColumns}{wxdbgetcolumns} function, but may be called if desired from the client application.
 981
 982 \wxheading{Parameters}
 983
 984 \docparam{tableName}{Name of the table for which the columns will be evaluated as to their inclusion in any indexes.}
 985 \docparam{colInf}{Data structure containing the column definitions (obtained with \helpref{wxDb::GetColumns}{wxdbgetcolumns}).  This function populates the PkCol, PkTableName, and FkTableName members of the colInf structure.}
 986 \docparam{numColumns}{Number of columns defined in the instance of colInf.}
 987
 988 \wxheading{Return value}
 989
 990 Currently always returns true.
 991
 992 \wxheading{See also}
 993
 994 \helpref{wxDbColInf}{wxdbcolinf}, \helpref{wxDb::GetColumns}{wxdbgetcolumns}
 995
 996 \membersection{wxDb::GetNext}\label{wxdbgetnext}
 997
 998 \func{bool}{GetNext}{\void}
 999
1000 Called after executing a query, this function requests the next row
1001 in the result set after the current position of the cursor.
1002
1003 \wxheading{See also}
1004
1005 \helpref{wxDb::ExecSql}{wxdbexecsql}, \helpref{wxDb::GetData}{wxdbgetdata}
1006
1007 \membersection{wxDb::GetNextError}\label{wxdbgetnexterror}
1008
1009 \func{bool}{GetNextError}{\param{HENV}{ aHenv},
1010 \param{HDBC}{ aHdbc = SQL\_NULL\_HDBC}, \param{HSTMT}{ aHstmt = SQL\_NULL\_HSTMT}}
1011
1012 \wxheading{Parameters}
1013
1014 \docparam{aHenv}{A handle to the ODBC environment.}
1015 \docparam{aHdbc}{{\it OPTIONAL.}  A handle to the ODBC connection.  Pass this
1016 in if the ODBC function call that failed required a hdbc or hstmt argument.}
1017 \docparam{AHstmt}{{\it OPTIONAL.}A handle to the ODBC statement being executed
1018 against.  Pass this in if the ODBC function call that failed requires a
1019 hstmt argument.}
1020
1021 \wxheading{Example}
1022
1023 \begin{verbatim}
1024    if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
1025    {
1026       return(db.GetNextError(db.henv, db.hdbc, hstmt));
1027    }
1028 \end{verbatim}
1029
1030 \wxheading{See also}
1031
1032 \helpref{wxDb::DispNextError}{wxdbdispnexterror},
1033 \helpref{wxDb::DispAllErrors}{wxdbdispallerrors}
1034
1035
1036 \membersection{wxDb::GetPassword}\label{wxdbgetpassword}
1037
1038 \func{const wxString \&}{GetPassword}{\void}
1039
1040 Returns the password used to establish this connection to the datasource.
1041
1042
1043 \membersection{wxDb::GetTableCount}\label{wxdbgettablecount}
1044
1045 \func{int }{GetTableCount}{\void}
1046
1047 Returns the number of wxDbTable() instances currently using this datasource
1048 connection.
1049
1050
1051 \membersection{wxDb::GetUsername}\label{wxdbgetusername}
1052
1053 \func{const wxString \&}{GetUsername}{\void}
1054
1055 Returns the user name (uid) used to establish this connection to the
1056 datasource.
1057
1058
1059 \membersection{wxDb::Grant}\label{wxdbgrant}
1060
1061 \func{bool}{Grant}{\param{int }{privileges}, \param{const wxString \&}{tableName},
1062 \param{const wxString \&}{userList = "PUBLIC"}}
1063
1064 Use this member function to GRANT privileges to users for accessing tables in
1065 the datasource.
1066
1067 \wxheading{Parameters}
1068
1069 \docparam{privileges}{Use this argument to select which privileges you want to
1070 grant.  Pass DB\_GRANT\_ALL to grant all privileges.  To grant individual
1071 privileges pass one or more of the following OR'd together:}
1072
1073 \begin{verbatim}
1074          DB_GRANT_SELECT  = 1
1075          DB_GRANT_INSERT  = 2
1076          DB_GRANT_UPDATE  = 4
1077          DB_GRANT_DELETE  = 8
1078          DB_GRANT_ALL     = DB_GRANT_SELECT | DB_GRANT_INSERT |
1079                             DB_GRANT_UPDATE | DB_GRANT_DELETE
1080 \end{verbatim}
1081
1082 \docparam{tableName}{The name of the table you wish to grant privileges on.}
1083 \docparam{userList}{{\it OPTIONAL.}  A comma delimited list of users to grant the privileges to.  If this argument is not passed in, the privileges will be given to the general PUBLIC.}
1084
1085 \wxheading{Remarks}
1086
1087 Some databases require user names to be specified in all capital letters (i.e. Oracle).  This function does not automatically capitalize the user names passed in the comma-separated list.  This is the responsibility of the calling routine.
1088
1089 The currently logged in user must have sufficient grantor privileges for this
1090 function to be able to successfully grant the indicated privileges.
1091
1092 \wxheading{Example}
1093
1094 \begin{verbatim}
1095    db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
1096 \end{verbatim}
1097
1098 \membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}
1099
1100 \func{bool}{IsFwdOnlyCursors}{\void}
1101
1102 This setting indicates whether this database connection was created
1103 as being capable of using only forward scrolling cursors.
1104
1105 This function does NOT indicate if the ODBC driver or datasource supports
1106 backward scrolling cursors.  There is no standard way of detecting if the
1107 driver or datasource can support backward scrolling cursors.
1108
1109 If a wxDb instance was created as being capable of only forward scrolling
1110 cursors, then even if the datasource and ODBC driver support backward
1111 scrolling cursors, tables using this database connection would only be able
1112 to use forward scrolling cursors.
1113
1114 The default setting of whether a wxDb connection to a database allows
1115 forward-only or also backward scrolling cursors is defined in setup.h by the
1116 value of wxODBC\_FWD\_ONLY\_CURSORS.  This default setting can be overridden
1117 when the wxDb connection is initially created (see
1118 \helpref{wxDb constructor}{wxdbctor} and \helpref{wxDbGetConnection}{wxdbfunctions}).
1119
1120 \wxheading{Return value}
1121
1122 Returns true if this datasource connection is defined as using only forward
1123 scrolling cursors, or false if the connection is defined as being allowed to
1124 use backward scrolling cursors and their associated functions (see note above).
1125
1126 \wxheading{Remarks}
1127
1128 Added as of wxWidgets v2.4 release, this function is a renamed version of
1129 wxDb::FwdOnlyCursors() to match the normal wxWidgets naming conventions for
1130 class member functions.
1131
1132 This function is not available in versions prior to v2.4.  You should
1133 use \helpref{wxDb::FwdOnlyCursors}{wxdbfwdonlycursors} for wxWidgets
1134 versions prior to 2.4.
1135
1136 \wxheading{See also}
1137
1138 \helpref{wxDb constructor}{wxdbctor}, \helpref{wxDbGetConnection}{wxdbfunctions}
1139
1140 \membersection{wxDb::IsOpen}\label{wxdbisopen}
1141
1142 \func{bool}{IsOpen}{\void}
1143
1144 Indicates whether the database connection to the datasource is currently
1145 opened.
1146
1147 \wxheading{Remarks}
1148
1149 This function may indicate that the database connection is open, even if
1150 the call to \helpref{wxDb::Open}{wxdbopen} may have failed to fully
1151 initialize the connection correctly.  The connection to the database
1152 {\it is} open and can be used via the direct SQL commands, if this
1153 function returns true.  Other functions which depend on the
1154 \helpref{wxDb::Open}{wxdbopen} to have completed correctly may not function
1155 as expected.  The return result from \helpref{wxDb::Open}{wxdbopen} is the
1156 only way to know if complete initialization of this wxDb connection was
1157 successful or not.  See \helpref{wxDb::Open}{wxdbopen} for more details on
1158 partial failures to open a connection instance.
1159
1160 \membersection{wxDb::LogError}\label{wxdblogerror}
1161
1162 \func{void}{LogError}{\param{const wxString \&}{errMsg} \param{const wxString \&}{SQLState=""}}
1163
1164 \docparam{errMsg}{Free-form text to display describing the error/text to be logged.}
1165 \docparam{SQLState}{{\it OPTIONAL.}  Native SQL state error.  Default is 0.}
1166
1167 \wxheading{Remarks}
1168
1169 Calling this function will enter a log message in the error list maintained
1170 for the database connection.  This log message is free form and can be
1171 anything the programmer wants to enter in the error list.
1172
1173 If SQL logging is turned on, the call to this function will also log the
1174 text into the SQL log file.
1175
1176 \wxheading{See also}
1177
1178 \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog}
1179
1180 \membersection{wxDb::ModifyColumn}\label{wxdbmodifycolumn}
1181
1182 \func{void}{ModifyColumn}{\param{const wxString \&}{tableName} \param{const wxString \&}{ColumnName}
1183 \param{int }{dataType} \param{ULONG }{columnLength=0} \param{const wxString \&}{optionalParam=""}}
1184
1185 Used to change certain properties of a column such as the length, or whether a column
1186 allows NULLs or not.
1187
1188 \docparam{tableName}{Name of the table that the column to be modified is in.}
1189 \docparam{columnName}{Name of the column to be modified.  NOTE: Name of column cannot
1190 be changed with this function.}
1191 \docparam{dataType}{Any one of DB\_DATA\_TYPE\_VARCHAR, DB\_DATA\_TYPE\_INTEGER,
1192 DB\_DATA\_TYPE\_FLOAT, DB\_DATA\_TYPE\_DATE.}
1193 \docparam{columnLength}{New size of the column.  Valid only for DB\_DATA\_TYPE\_VARCHAR
1194 dataType fields.  Default is 0.}
1195 \docparam{optionalParam}{Default is "".}
1196
1197 \wxheading{Remarks}
1198
1199 Cannot be used to modify the precision of a numeric column, therefore 'columnLength'
1200 is ignored unless the dataType is DB\_DATA\_TYPE\_VARCHAR.
1201
1202 Some datasources do not allow certain properties of a column to be changed if any rows
1203 currently have data stored in that column.  Those datasources that do allow columns
1204 to be changed with data in the rows many handle truncation and/or expansion in
1205 different ways.  Please refer to the reference material for the datasource being
1206 used for behavioral descriptions.
1207
1208 \wxheading{Example}
1209
1210 \begin{verbatim}
1211     ok = pDb->ModifyColumn("CONTACTS", "ADDRESS2",
1212                             DB_, colDefs[j].SzDataObj,
1213                             wxT("NOT NULL"));
1214 \end{verbatim}
1215
1216
1217 \membersection{wxDb::Open}\label{wxdbopen}
1218
1219 \func{bool}{Open}{\param{const wxString \&}{Dsn}, \param{const wxString \&}{Uid},
1220 \param{const wxString \&}{AuthStr}, \param{bool }{failOnDataTypeUnsupported}}
1221
1222 \func{bool}{Open}{\param{const wxString \&}{inConnectStr},
1223 \param{bool }{failOnDataTypeUnsupported}}
1224
1225 \func{bool}{Open}{\param{wxDbConnectInf *}{dbConnectInf},
1226 \param{bool }{failOnDataTypeUnsupported}}
1227
1228 \func{bool}{Open}{\param{wxDb *}{copyDb}}
1229
1230 Opens a connection to the datasource, sets certain behaviors of the datasource
1231 to confirm to the accepted behaviors (e.g. cursor position maintained on
1232 commits), and queries the datasource for its representations of the basic
1233 datatypes to determine the form in which the data going to/from columns in
1234 the data tables are to be handled.
1235
1236 The second form of this function, which accepts a "wxDb *" as a parameter,
1237 can be used to avoid the overhead (execution time, database load, network
1238 traffic) which are needed to determine the data types and representations
1239 of data that are necessary for cross-datasource support by these classes.
1240
1241 Normally the first form of the wxDb::Open() function will open the connection
1242 and then send a series of queries to the datasource asking it for its
1243 representation of data types, and all the features it supports.  If one
1244 connection to the datasource has already been made previously, the information
1245 gathered when that connection was created can just be copied to any new
1246 connections to the same datasource by passing a pointer to the first
1247 connection in as a parameter to the wxDb::Open() function.  Note that this
1248 new connection created from the first connections information will use the
1249 same Dsn/Uid/AuthStr as the first connection used.
1250
1251 \wxheading{Parameters}
1252
1253 \docparam{Dsn}{datasource name.  The name of the ODBC datasource as
1254 assigned when the datasource is initially set up through the ODBC data
1255 source manager.}
1256 \docparam{Uid}{User ID.  The name (ID) of the user you wish to connect as
1257 to the datasource.  The user name (ID) determines what objects you
1258 have access to in the datasource and what datasource privileges you have.
1259 Privileges include being able to create new objects, update objects, delete
1260 objects and so on.  Users and privileges are normally administered by the
1261 database administrator.}
1262 \docparam{AuthStr}{The password associated with the Uid.}
1263 \docparam{failOnDataTypeUnsupporte}{As part of connecting to a database, the
1264 wxDb::Open() function will query the database to find out the native types
1265 that it supports.  With some databases, some data types may not be supported,
1266 or not sufficiently supported, for use with the wxODBC classes.  Normally
1267 a program should fail in this case, so as not to try to use a data type
1268 that is not supported.  This parameter allows the programmer to override the
1269 failure if they wish and continue on using the connection.}
1270 \docparam{dbConnectInf}{Contains a DSN, Uid, Password, or a connection string
1271 to be used in opening a new connection to the database.  If a connection
1272 string is present, then the connection string will be used.  If there is no
1273 connection string present, then the DSN, Uid, and Password are used.}
1274 \docparam{inConnectStr}{A valid ODBC connection string used to connect to a
1275 database}
1276 \docparam{copyDb}{Already completely configured and opened datasource
1277 connection from which all Dsn, Uid, AuthStr, connection string, and data
1278 typing information is to be copied from for use by this datasource
1279 connection.  If 'copyDb' used a connection string to create its connection
1280 originally, then the connection being made by this call to wxDb::Open() will
1281 use that same connection string.}
1282
1283 \wxheading{Remarks}
1284
1285 After a wxDb instance is created, it must then be opened.  When opening a
1286 datasource, there must be three pieces of information passed.  The data
1287 source name, user name (ID) and the password for the user.  No database
1288 activity on the datasource can be performed until the connection is opened.
1289 This is normally done at program startup and the datasource remains
1290 open for the duration of the program/module run.
1291
1292 It is possible to have connections to multiple datasources open at the same
1293 time to support distributed database connections by having separate instances
1294 of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.
1295
1296 If this function returns a value of false, it does not necessarily mean that
1297 the connection to the datasource was not opened.  It may mean that some
1298 portion of the initialization of the connection failed (such as a datatype not
1299 being able to be determined how the datasource represents it).  To determine
1300 if the connection to the database failed, use the \helpref{wxDb::IsOpen}{wxdbisopen}
1301 function after receiving a false result back from this function to determine if
1302 the connection was opened or not.  If this function returns false, but \helpref{wxDb::IsOpen}{wxdbisopen}
1303 returns true, then direct SQL commands may be passed to the database
1304 connection and can be successfully executed, but use of the datatypes (such as
1305 by a wxDbTable instance) that are normally determined during open will not be
1306 possible.
1307
1308 \normalbox{The {\it Dsn}, {\it Uid}, and {\it AuthStr} string pointers that are passed in
1309 are copied.  NOT the strings themselves, only the pointers.  The calling routine
1310 must maintain the memory for these three strings for the life of the wxDb instance.}
1311
1312 \wxheading{Example}
1313
1314 \begin{verbatim}
1315    wxDb sampleDB(DbConnectInf.GetHenv());
1316    if (!sampleDB.Open("Oracle 7.1 HP/UX", "gtasker", "myPassword"))
1317    {
1318       if (sampleDb.IsOpen())
1319       {
1320         // Connection is open, but the initialization of
1321         // datatypes and parameter settings failed
1322       }
1323       else
1324       {
1325         // Error opening datasource
1326       }
1327    }
1328 \end{verbatim}
1329
1330 \membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}
1331
1332 \func{bool}{RollbackTrans}{\void}
1333
1334 Function to "undo" changes made to the database.  After an insert/update/delete, the operation may be "undone" by issuing this command any time before a \helpref{wxDb::CommitTrans}{wxdbcommittrans} is called on the database connection.
1335
1336 \wxheading{Remarks}
1337
1338 Transactions begin implicitly as soon as you make a change to the database.  The
1339 transaction continues until either a commit or rollback is executed.  Calling
1340 wxDb::RollbackTrans() will result in ALL changes done using this database
1341 connection that have not already been committed to be "undone" back to the last
1342 commit/rollback that was successfully executed.
1343
1344 \normalbox{Calling this member function rolls back ALL open (uncommitted)
1345 transactions on this ODBC connection, including all wxDbTable instances that
1346 use this connection.}
1347
1348 \wxheading{See also}
1349
1350 \helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors
1351
1352 \membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
1353
1354 \func{void}{SetDebugErrorMessages}{\param{bool }{state}}
1355
1356 \docparam{state}{Either true (debug messages are logged) or false (debug
1357 messages are not logged).}
1358
1359 \wxheading{Remarks}
1360
1361 Turns on/off debug error messages from the ODBC class library.  When
1362 this function is passed true, errors are reported to the user/logged automatically
1363 in a text or pop-up dialog when an ODBC error occurs.  When passed false,
1364 errors are silently handled.
1365
1366 When compiled in release mode (FINAL=1), this setting has no affect.
1367
1368 \wxheading{See also}
1369
1370 \helpref{wxDb constructor}{wxdbctor}
1371
1372 \membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
1373
1374 \func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxString \&}{filename = SQL\_LOG\_FILENAME}, \param{bool }{ append = false}}
1375
1376 \wxheading{Parameters}
1377
1378 \docparam{state}{Either sqlLogOFF or sqlLogON (see \helpref{enum wxDbSqlLogState}{wxdbcolfor}). Turns logging of SQL commands sent to the datasource OFF or ON.}
1379 \docparam{filename}{{\it OPTIONAL}.  Name of the file to which the log text is to be written.  Default is SQL\_LOG\_FILENAME.}
1380 \docparam{append}{{\it OPTIONAL}. Whether the file is appended to or overwritten.  Default is false.}
1381
1382 \wxheading{Remarks}
1383
1384 When called with {\it sqlLogON}, all commands sent to the datasource engine are logged to the file specified by {\it filename}.  Logging is done by embedded \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} calls in the database member functions, or may be manually logged by adding calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} in your own source code.
1385
1386 When called with {\it sqlLogOFF}, the logging file is closed, and any calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} are ignored.
1387
1388 \membersection{wxDb::SQLColumnName}\label{wxdbsqlcolumnname}
1389
1390 \func{const wxString}{SQLColumnName}{\param{const wxChar *}{ colName}}
1391
1392 Returns the column name in a form ready for use in SQL statements.
1393 In most cases, the column name is returned verbatim.  But some databases
1394 (e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which
1395 must be specially quoted.  For example, if the datasource allows spaces
1396 in the column name, the returned string will have the correct enclosing
1397 marks around the name to allow it to be properly included in a SQL statement
1398 for the DBMS that is currently connected to with this connection.
1399
1400 \wxheading{Parameters}
1401
1402 \docparam{colName}{Native name of the column in the table that is to be
1403 evaluated to determine if any special quoting marks needed to be added to it
1404 before including the column name in a SQL statement}
1405
1406 \wxheading{See also}
1407
1408 \helpref{wxDb::SQLTableName}{wxdbsqltablename}
1409
1410 \membersection{wxDb::SQLTableName}\label{wxdbsqltablename}
1411
1412 \func{const wxString}{SQLTableName}{\param{const wxChar *}{ tableName}}
1413
1414 Returns the table name in a form ready for use in SQL statements.
1415 In most cases, the table name is returned verbatim.  But some databases
1416 (e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which
1417 must be specially quoted.  For example, if the datasource allows spaces
1418 in the table name, the returned string will have the correct enclosing
1419 marks around the name to allow it to be properly included in a SQL statement
1420 for the data source that is currently connected to with this connection.
1421
1422 \wxheading{Parameters}
1423
1424 \docparam{tableName}{Native name of the table that is to be evaluated to
1425 determine if any special quoting marks needed to be added to it
1426 before including the table name in a SQL statement}
1427
1428 \wxheading{See also}
1429
1430 \helpref{wxDb::SQLColumnName}{wxdbsqlcolumnname}
1431
1432 \membersection{wxDb::TableExists}\label{wxdbtableexists}
1433
1434 \func{bool}{TableExists}{\param{const wxString \&}{tableName}, \param{const wxChar *}{userID=NULL}, \param{const wxString \&}{path=""}}
1435
1436 Checks the ODBC datasource for the existence of a table.  If a {\it userID}
1437 is specified, then the table must be accessible by that user (user must have
1438 at least minimal privileges to the table).
1439
1440 \wxheading{Parameters}
1441
1442 \docparam{tableName}{Name of the table to check for the existence of.}
1443 \docparam{userID}{Owner of the table (also referred to as schema).  Specify a userID when the datasource you are connected
1444 to allows multiple unique tables with the same name to be owned by different users.  {\it userID}
1445 is evaluated as follows:}
1446
1447 \begin{verbatim}
1448          userID == NULL  ... UserID is ignored (DEFAULT)
1449          userID == ""    ... UserID set equal to 'this->uid'
1450          userID != ""    ... UserID set equal to 'userID'
1451 \end{verbatim}
1452
1453 \wxheading{Remarks}
1454
1455 {\it tableName} may refer to a table, view, alias or synonym.
1456
1457 This function does not indicate whether or not the user has privileges to query or perform other functions on the table.  Use the \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} to determine if the user has sufficient privileges or not.
1458
1459 \wxheading{See also}
1460
1461 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
1462
1463 \membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}
1464
1465 \func{bool}{TablePrivileges}{\param{const wxString \&}{tableName}, \param{const wxString \&}{priv},
1466 \param{const wxChar *}{userID=NULL}, \param{const wxChar *}{schema=NULL},
1467 \param{const wxString \&}{path=""}}
1468
1469 Checks the ODBC datasource for the existence of a table.  If a {\it userID}
1470 is specified, then the table must be accessible by that user (user must have
1471 at least minimal privileges to the table).
1472
1473 \wxheading{Parameters}
1474
1475 \docparam{tableName}{Name of the table on which to check privileges.
1476 {\it tableName} may refer to a table, view, alias or synonym.}
1477 \docparam{priv}{The table privilege being evaluated. May be one of the
1478 following (or a datasource specific privilege):}
1479
1480 \begin{verbatim}
1481     SELECT      : The connected user is permitted to retrieve data for
1482                   one or more columns of the table.
1483
1484     INSERT      : The connected user is permitted to insert new rows
1485                   containing data for one or more columns into the
1486                   table.
1487
1488     UPDATE      : The connected user is permitted to update the data in
1489                   one or more columns of the table.
1490
1491     DELETE      : The connected user is permitted to delete rows of
1492                   data from the table.
1493
1494     REFERENCES  : Is the connected user permitted to refer to one or
1495                   more columns of the table within a constraint (for
1496                   example, a unique, referential, or table check
1497                   constraint).
1498 \end{verbatim}
1499
1500 \docparam{userID}{{\it OPTIONAL.}  User for which to determine if the privilege
1501 specified to be checked is granted or not.  Default is "".
1502 {\it userID} is evaluated as follows:}
1503
1504 \begin{verbatim}
1505          userID == NULL  ... NOT ALLOWED!
1506          userID == ""    ... UserID set equal to 'this->uid'
1507          userID != ""    ... UserID set equal to 'userID'
1508 \end{verbatim}
1509
1510 \docparam{schema}{{\it OPTIONAL.}  Owner of the table.  Specify a userID when the datasource
1511 you are connected to allows multiple unique tables with the same name to be
1512 owned by different users.  Specifying the table owner makes determination of the
1513 users privileges MUCH faster.  Default is NULL.  {\it userID} is
1514 evaluated as follows:}
1515
1516 \begin{verbatim}
1517          schema == NULL  ... Any owner (DEFAULT)
1518          schema == ""    ... Owned by 'this->uid'
1519          schema != ""    ... Owned by userID specified in 'schema'
1520 \end{verbatim}
1521
1522 \docparam{path}{{\it OPTIONAL.}  Path to the table.  Default is "".
1523 Currently unused.}
1524
1525 \wxheading{Remarks}
1526
1527 The scope of privilege allowed to the connected user by a given table
1528 privilege is datasource dependent.
1529
1530 For example, the privilege UPDATE might allow the connected user to update
1531 all columns in a table on one datasource, but only those columns for
1532 which the grantor (the user that granted the connected user) has the UPDATE
1533 privilege on another datasource.
1534
1535 Looking up a user's privileges to a table can be time consuming depending on the
1536 datasource and ODBC driver.  This time can be minimized by passing a {\it schema}
1537 as a parameter.  With some datasources/drivers, the difference can be several
1538 seconds of time difference.
1539
1540
1541 \membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}
1542
1543 \func{int }{TranslateSqlState}{\param{const wxString \&}{SQLState}}
1544
1545 Converts an ODBC sqlstate to an internal error code.
1546
1547 \wxheading{Parameters}
1548
1549 \docparam{SQLState}{State to be converted.}
1550
1551 \wxheading{Return value}
1552
1553 Returns the internal class DB\_ERR code.  See \helpref{wxDb::DB\_STATUS}{wxdb} definition.
1554
1555 \membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
1556
1557 \func{bool}{WriteSqlLog}{\param{const wxString \&}{logMsg}}
1558
1559 \wxheading{Parameters}
1560
1561 \docparam{logMsg}{Free form string to be written to the log file.}
1562
1563 \wxheading{Remarks}
1564
1565 Very useful debugging tool that may be turned on/off during run time (see
1566 (see \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging} for details on
1567 turning logging on/off).  The passed in string {\it logMsg} will be written to
1568 a log file if SQL logging is turned on.
1569
1570 \wxheading{Return value}
1571
1572 If SQL logging is off when a call to WriteSqlLog() is made, or there is a
1573 failure to write the log message to the log file, the function returns
1574 false without performing the requested log, otherwise true is returned.
1575
1576 \wxheading{See also}
1577
1578 \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
1579
1580 \section{\class{wxDbColDataPtr}}\label{wxdbcoldataptr}
1581
1582 Pointer to dynamic column definitions for use with a wxDbTable instance.
1583 Currently there are no member functions for this class.
1584
1585 See the \helpref{database classes overview}{odbcoverview} for
1586 an introduction to using the ODBC classes.
1587
1588 \begin{verbatim}
1589     void   *PtrDataObj;
1590     int     SzDataObj;
1591     SWORD   SqlCtype;
1592 \end{verbatim}
1593
1594 \section{\class{wxDbColDef}}\label{wxdbcoldef}
1595
1596 This class is used to hold information about the columns bound to an
1597 instance of a wxDbTable object.
1598
1599 Each instance of this class describes one column in the wxDbTable
1600 object.  When calling the \helpref{wxDb constructor}{wxdbctor}, a
1601 parameter passed in indicates the number of columns that will be defined for
1602 the wxDbTable object.  The constructor uses this information to allocate
1603 adequate memory for all of the column descriptions in your wxDbTable object.
1604 Private member wxDbTable::colDefs is a pointer to this chunk of memory
1605 maintained by the wxDbTable class (and can be retrieved using the
1606 \helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs} function).
1607 To access the nth column definition of your wxDbTable object, just reference
1608 wxDbColDefs element [n - 1].
1609
1610 Typically, \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} is used to
1611 populate an array of these data structures for the wxDbTable instance.
1612
1613 Currently there are no accessor functions for this class, so all members are
1614 public.
1615
1616 \begin{verbatim}
1617     wxChar  ColName[DB_MAX_COLUMN_NAME_LEN+1];  // Column Name
1618     int     DbDataType;    - Logical Data Type;
1619                              e.g. DB_DATA_TYPE_INTEGER
1620     SWORD   SqlCtype;      - C data type; e.g. SQL_C_LONG
1621     void   *PtrDataObj;    - Address of the data object
1622     int     SzDataObj;     - Size, in bytes, of the data object
1623     bool    KeyField;      - Is column part of the PRIMARY KEY for the
1624                              table? -- Date fields should NOT be
1625                              KeyFields
1626     bool    Updateable;    - Column is updateable?
1627     bool    InsertAllowed; - Column included in INSERT statements?
1628     bool    DerivedCol;    - Column is a derived value?
1629     SDWORD  CbValue;       - !!!Internal use only!!!
1630     bool    Null;          - NOT FULLY IMPLEMENTED
1631                              Allows NULL values in Inserts and Updates
1632 \end{verbatim}
1633
1634 \wxheading{See also}
1635
1636 \helpref{database classes overview}{odbcoverview},
1637 \helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs}, \helpref{wxDb constructor}{wxdbctor}
1638
1639 \wxheading{Include files}
1640
1641 <wx/db.h>
1642
1643 \latexignore{\rtfignore{\wxheading{Members}}}
1644
1645 \membersection{wxDbColDef::Initialize}\label{wxdbcoldefinitialize}
1646
1647 Simply initializes all member variables to a cleared state.  Called by
1648 the constructor automatically.
1649
1650 \section{\class{wxDbColFor}}\label{wxdbcolfor}
1651
1652 Beginning support for handling international formatting specifically on dates
1653 and floats.
1654
1655 \begin{verbatim}
1656     wxString       s_Field;       // Formatted String for Output
1657     wxString       s_Format[7];   // Formatted Objects - TIMESTAMP has
1658                                      the biggest (7)
1659     wxString       s_Amount[7];   // Formatted Objects - amount of
1660                                      things that can be formatted
1661     int            i_Amount[7];   // Formatted Objects -
1662                                         TT MM YYYY HH MM SS m
1663     int            i_Nation;      // 0 = timestamp
1664                                      1 = EU
1665                                      2 = UK
1666                                      3 = International
1667                                      4 = US
1668     int            i_dbDataType;  // conversion of the 'sqlDataType'
1669                                      to the generic data type used by
1670                                      these classes
1671     SWORD          i_sqlDataType;
1672 \end{verbatim}
1673
1674 The constructor for this class initializes all the values to zero or NULL.
1675
1676 The destructor does nothing at this time.
1677
1678 Only one function is provided with this class currently.
1679
1680 See the \helpref{database classes overview}{odbcoverview} for
1681 an introduction to using the ODBC classes.
1682
1683 \wxheading{Include files}
1684
1685 <wx/db.h>
1686
1687 \wxheading{Library}
1688
1689 \helpref{wxOdbc}{librarieslist}
1690
1691 \latexignore{\rtfignore{\wxheading{Members}}}
1692
1693 \membersection{wxDbColFor::Format}\label{wxdbcolforformat}
1694
1695 \func{int }{Format}{\param{int }{Nation}, \param{int }{dbDataType},
1696 \param{SWORD }{sqlDataType}, \param{short }{columnSize},
1697 \param{short }{decimalDigits}}\label{wxdbcolforformat}
1698
1699 Work in progress, and should be inter-related with wxLocale eventually.
1700
1701 \membersection{wxDbColFor::Initialize}\label{wxdbcolforinitialize}
1702
1703 Simply initializes all member variables to a cleared state.  Called by
1704 the constructor automatically.
1705
1706 \section{\class{wxDbColInf}}\label{wxdbcolinf}
1707
1708 Used with the \helpref{wxDb::GetColumns}{wxdbgetcolumns} functions for obtaining all retrievable information about a column's definition.
1709
1710 \begin{verbatim}
1711     wxChar       catalog[128+1];
1712     wxChar       schema[128+1];
1713     wxChar       tableName[DB_MAX_TABLE_NAME_LEN+1];
1714     wxChar       colName[DB_MAX_COLUMN_NAME_LEN+1];
1715     SWORD        sqlDataType;
1716     wxChar       typeName[128+1];
1717     SWORD        columnSize;
1718     SWORD        bufferLength;
1719     short        decimalDigits;
1720     short        numPrecRadix;
1721     short        nullable;
1722     wxChar       remarks[254+1];
1723     int          dbDataType;  // conversion of the 'sqlDataType'
1724                               // to the generic data type used by
1725                               // these classes
1726     int          PkCol;       // Primary key column
1727                                     0 = No
1728                                     1 = First Key
1729                                     2 = Second Key, etc...
1730     wxChar       PkTableName[DB_MAX_TABLE_NAME_LEN+1];
1731                               // Tables that use this PKey as a FKey
1732     int          FkCol;       // Foreign key column
1733                                     0 = No
1734                                     1 = First Key
1735                                     2 = Second Key, etc...
1736     wxChar       FkTableName[DB_MAX_TABLE_NAME_LEN+1];
1737                               // Foreign key table name
1738     wxDbColFor  *pColFor;     // How should this column be formatted
1739 \end{verbatim}
1740
1741 The constructor for this class initializes all the values to zero, "", or NULL.
1742
1743 The destructor for this class takes care of deleting the pColFor member if
1744 it is non-NULL.
1745
1746 See the \helpref{database classes overview}{odbcoverview} for
1747 an introduction to using the ODBC classes.
1748
1749 \wxheading{Include files}
1750
1751 <wx/db.h>
1752
1753 \wxheading{Library}
1754
1755 \helpref{wxOdbc}{librarieslist}
1756
1757 \latexignore{\rtfignore{\wxheading{Members}}}
1758
1759 \membersection{wxDbColInf::Initialize}\label{wxdbcolinfinitialize}
1760
1761 Simply initializes all member variables to a cleared state.  Called by
1762 the constructor automatically.
1763
1764 \section{\class{wxDbConnectInf}}\label{wxdbconnectinf}
1765
1766 This class is used for holding the data necessary for connecting to the ODBC
1767 datasource.  That information includes: SQL environment handle, datasource
1768 name, user ID, password and default directory path (used with dBase).  Other
1769 optional fields held in this class are and file type, both for future
1770 functions planned to be added for creating/manipulating datasource definitions.
1771
1772 \membersection{wxDbConnectInf::wxDbConnectInf}\label{wxdbconnectinfctor}
1773
1774 \func{}{wxDbConnectInf}{\void}
1775
1776 Default constructor.
1777
1778 \func{}{wxDbConnectInf}{\param{HENV }{henv}, \param{const wxString \&}{dsn},
1779 \param{const wxString \&}{userID=""}, \param{const wxString \&}{password},
1780 \param{const wxString \&}{defaultDir=""}, \param{const wxString \&}{description=""},
1781 \param{const wxString \&}{fileType=""}}
1782
1783 Constructor which allows initial settings of all the classes member variables.
1784
1785 See the special note below on the henv parameter for forcing this constructor
1786 to create a SQL environment handle automatically, rather than needing to pass
1787 one in to the function.
1788
1789 \wxheading{Parameters}
1790
1791 \docparam{henv}{Environment handle used for this connection.  See\rtfsp
1792 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv} for how to create
1793 an SQL environment handle.  NOTE: Passing in a NULL for this parameter will
1794 inform the constructor that it should create its own SQL environment handle.
1795 If NULL is passed for this parameter, the constructor will call\rtfsp
1796 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv} internally.  A
1797 flag is set internally also to indicate that the HENV was created by the
1798 constructor so that when the default class destructor is called, the
1799 destructor will call \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}\rtfsp
1800 to free the environment handle automatically.}
1801 \docparam{dsn}{Name of the datasource to be used in creating wxDb instances
1802 for creating connection(s) to a datasource.}
1803 \docparam{userID}{{\it OPTIONAL} Many datasources allow (or even require)
1804 use of a username to determine privileges that connecting user is allowed
1805 to have when accessing the datasource or the data tables.  Default is "".}
1806 \docparam{password}{{\it OPTIONAL} Password to be associated with the user
1807 ID specified in 'userID'.  Default is "".}
1808 \docparam{defaultDir}{{\it OPTIONAL} Used for datasources which require the
1809 path to where the data file is stored to be specified.  dBase is one example
1810 of the type of datasource which requires this information.  Default is "".}
1811 \docparam{description}{{\it OPTIONAL} {\bf FUTURE USE} Default is "".}
1812 \docparam{fileType}{{\it OPTIONAL} {\bf FUTURE USE} Default is "".}
1813
1814 \wxheading{Remarks}
1815
1816 It is strongly recommended that programs use the longer form of the
1817 constructor and allow the constructor to create the SQL environment handle
1818 automatically, and manage the destruction of the handle.
1819
1820 \wxheading{Example}
1821
1822 \begin{verbatim}
1823    wxDbConnectInf *DbConnectInf;
1824
1825         DbConnectInf = new wxDbConnectInf(0,"MY_DSN", "MY_USER", "MY_PASSWORD");
1826
1827         ....the rest of the program
1828
1829         delete DbConnectInf;
1830 \end{verbatim}
1831
1832 \wxheading{See also}
1833
1834 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv},
1835 \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}
1836
1837 \membersection{wxDbConnectInf::\destruct{wxDbConnectInf}}\label{wxdbconnectinfdestr}
1838
1839 \func{}{\destruct{wxDbConnectInf}}{}
1840
1841 Handles the default destruction of the instance of the class.  If the long form
1842 of the \helpref{wxDConnectInf}{wxdbconnectinf} was used, then this destructor
1843 also takes care of calling\rtfsp
1844 \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv} to free the
1845 SQL environment handle.
1846
1847 \membersection{wxDbConnectInf::AllocHenv}\label{wxdbconnectinfallochenv}
1848
1849 \func{bool }{AllocHenv}{\void}
1850
1851 Allocates a SQL environment handle that will be used to interface with
1852 an ODBC datasource.
1853
1854 \wxheading{Remarks}
1855
1856 This function can be automatically called by the long from of the
1857 \helpref{wxDbConnectInf}{wxdbconnectinf} constructor.
1858
1859 \membersection{wxDbConnectInf::FreeHenv}\label{wxdbconnectinffreehenv}
1860
1861 \func{void}{FreeHenv}{\void}
1862
1863 Frees the SQL environment handle being managed by the instance of this class.
1864
1865 \wxheading{Remarks}
1866
1867 If the SQL environment handle was created using the long form of the\rtfsp
1868 \helpref{wxDbConnectInf}{wxdbconnectinf} constructor, then the flag indicating
1869 that the HENV should be destroyed when the classes destructor is called
1870 is reset to be false, so that any future handles created using the\rtfsp
1871 \helpref{wxDbConnectInf::AllocHenv}{wxdbconnectinfallochenv} function
1872 must be manually released with a call to this function.
1873
1874 \membersection{wxDbConnectInf::Initialize}\label{wxdbconnectinfinitialize}
1875
1876 Simply initializes all member variables to a cleared state.  Called by
1877 the constructor automatically.
1878
1879 \membersection{wxDbConnectInf::GetAuthStr}\label{wxdbconnectinfgetauthstr}
1880
1881 \func{const wxChar *}{GetAuthStr}{\void}
1882
1883 Accessor function to return the password assigned for this class
1884 instance that will be used with the user ID.
1885
1886 Synonymous with \helpref{wxDbConnectInf::GetPassword}{wxdbconnectinfgetpassword}
1887
1888 \membersection{wxDbConnectInf::GetDefaultDir}\label{wxdbconnectinfgetdefaultdir}
1889
1890 \func{const wxChar *}{GetDefaultDir}{\void}
1891
1892 Accessor function to return the default directory in which the datasource's data
1893 table is stored.  This directory is only used for file based datasources like
1894 dBase.  MS-Access does not require this to be set, as the path is set in the
1895 ODBC Administrator for MS-Access.
1896
1897 \membersection{wxDbConnectInf::GetDescription}\label{wxdbconnectinfgetdescription}
1898
1899 \func{const wxChar *}{GetDescription}{\void}
1900
1901 Accessor function to return the description assigned for this class
1902 instance.
1903
1904 NOTE: Description is a FUTURE USE item and is unused currently.
1905
1906 \membersection{wxDbConnectInf::GetDsn}\label{wxdbconnectinfgetdsn}
1907
1908 \func{const wxChar *}{GetDsn}{\void}
1909
1910 Accessor function to return the datasource name assigned for this class
1911 instance.
1912
1913 \membersection{wxDbConnectInf::GetFileType}\label{wxdbconnectinfgetfiletype}
1914
1915 \func{const wxChar *}{GetFileType}{\void}
1916
1917 Accessor function to return the filetype of the ODBC datasource assigned for
1918 this class instance.
1919
1920 NOTE: FileType is a FUTURE USE item and is unused currently.
1921
1922 \membersection{wxDbConnectInf::GetHenv}\label{wxdbconnectinfgethenv}
1923
1924 \func{const HENV}{GetHenv}{\void}
1925
1926 Accessor function to return the SQL environment handle being managed
1927 by this class instance.
1928
1929 \membersection{wxDbConnectInf::GetPassword}\label{wxdbconnectinfgetpassword}
1930
1931 \func{const wxChar *}{GetPassword}{\void}
1932
1933 Accessor function to return the password assigned for this class
1934 instance that will be used with the user ID.
1935
1936 Synonymous with \helpref{wxDbConnectInf::GetAuthStr}{wxdbconnectinfgetauthstr}
1937
1938 \membersection{wxDbConnectInf::GetUid}\label{wxdbconnectinfgetuid}
1939
1940 \func{const wxChar *}{GetUid}{\void}
1941
1942 Accessor function to return the user ID assigned for this class
1943 instance.
1944
1945 \membersection{wxDbConnectInf::GetUserID}\label{wxdbconnectinfgetuserid}
1946
1947 \func{const wxChar *}{GetUserID}{\void}
1948
1949 Accessor function to return the user ID assigned for this class
1950 instance.
1951
1952 \membersection{wxDbConnectInf::SetAuthStr}\label{wxdbconnectinfsetauthstr}
1953
1954 \func{\void}{SetAuthStr}{const wxString \&authstr}
1955
1956 Accessor function to assign the password for this class
1957 instance that will be used with the user ID.
1958
1959 Synonymous with \helpref{wxDbConnectInf::SetPassword}{wxdbconnectinfsetpassword}
1960
1961 \membersection{wxDbConnectInf::SetDefaultDir}\label{wxdbconnectinfsetdefaultdir}
1962
1963 \func{\void}{SetDefaultDir}{const wxString \&defDir}
1964
1965 Accessor function to assign the default directory in which the datasource's data
1966 table is stored.  This directory is only used for file based datasources like
1967 dBase.  MS-Access does not require this to be set, as the path is set in the
1968 ODBC Administrator for MS-Access.
1969
1970 \membersection{wxDbConnectInf::SetDescription}\label{wxdbconnectinfsetdescription}
1971
1972 \func{\void}{SetDescription}{const wxString \&desc}
1973
1974 Accessor function to assign the description assigned for this class
1975 instance.
1976
1977 NOTE: Description is a FUTURE USE item and is unused currently.
1978
1979 \membersection{wxDbConnectInf::SetDsn}\label{wxdbconnectinfsetdsn}
1980
1981 \func{\void}{SetDsn}{const wxString \&dsn}
1982
1983 Accessor function to assign the datasource name for this class instance.
1984
1985 \membersection{wxDbConnectInf::SetFileType}\label{wxdbconnectinfsetfiletype}
1986
1987 \func{\void}{SetFileType}{const wxString \&}
1988
1989 Accessor function to return the filetype of the ODBC datasource assigned for
1990 this class instance.
1991
1992 NOTE: FileType is a FUTURE USE item and is unused currently.
1993
1994 \membersection{wxDbConnectInf::SetHenv}\label{wxdbconnectinfsethenv}
1995
1996 \func{void}{SetHenv}{\param{const HENV }{henv}}
1997
1998 Accessor function to set the SQL environment handle for this class instance.
1999
2000 \membersection{wxDbConnectInf::SetPassword}\label{wxdbconnectinfsetpassword}
2001
2002 \func{\void}{SetPassword}{const wxString \&password}
2003
2004 Accessor function to assign the password for this class
2005 instance that will be used with the user ID.
2006
2007 Synonymous with \helpref{wxDbConnectInf::SetAuthStr}{wxdbconnectinfsetauthstr}
2008
2009 \membersection{wxDbConnectInf::SetUid}\label{wxdbconnectinfsetuid}
2010
2011 \func{\void}{SetUid}{const wxString \&uid}
2012
2013 Accessor function to set the user ID for this class instance.
2014
2015 \membersection{wxDbConnectInf::SetUserID}\label{wxdbconnectinfsetuserid}
2016
2017 \func{\void}{SetUserID}{const wxString \&userID}
2018
2019 Accessor function to assign the user ID for this class instance.
2020
2021 \section{\class{wxDbIdxDef}}\label{wxdbidxdef}
2022
2023 Used in creation of non-primary indexes.  Currently there are no member
2024 functions for this class.
2025
2026 \begin{verbatim}
2027         wxChar  ColName[DB_MAX_COLUMN_NAME_LEN+1]
2028                                   // Name of column
2029         bool    Ascending         // Is index maintained in
2030                                      ASCENDING sequence?
2031 \end{verbatim}
2032
2033 There are no constructors/destructors as of this time, and no member functions.
2034
2035 See the \helpref{database classes overview}{odbcoverview} for
2036 an introduction to using the ODBC classes.
2037
2038
2039 \wxheading{Include files}
2040
2041 <wx/db.h>
2042
2043 \wxheading{Library}
2044
2045 \helpref{wxOdbc}{librarieslist}
2046
2047 \section{\class{wxDbInf}}\label{wxdbinf}
2048
2049 Contains information regarding the database connection (datasource name,
2050 number of tables, etc).  A pointer to a wxDbTableInf is included in this
2051 class so a program can create a wxDbTableInf array instance to maintain all
2052 information about all tables in the datasource to have all the datasource's
2053 information in one memory structure.
2054
2055 Primarily, this class is used internally by the wxWidgets ODBC classes.
2056
2057 \begin{verbatim}
2058     wxChar        catalog[128+1];
2059     wxChar        schema[128+1];  // typically means owner of table(s)
2060     int           numTables;      // How many tables does this
2061                                      datasource have
2062     wxDbTableInf *pTableInf;      // Equals a new
2063                                      wxDbTableInf[numTables];
2064 \end{verbatim}
2065
2066 The constructor for this class initializes all the values to zero, "", or NULL.
2067
2068 The destructor for this class takes care of deleting the pTableInf member if
2069 it is non-NULL.
2070
2071 See the \helpref{database classes overview}{odbcoverview} for
2072 an introduction to using the ODBC classes.
2073
2074 \wxheading{Include files}
2075
2076 <wx/db.h>
2077
2078 \wxheading{Library}
2079
2080 \helpref{wxOdbc}{librarieslist}
2081
2082 \latexignore{\rtfignore{\wxheading{Members}}}
2083
2084 \membersection{wxDbInf::Initialize}\label{wxdbinfinitialize}
2085
2086 Simply initializes all member variables to a cleared state.  Called by
2087 the constructor automatically.
2088
2089 \section{\class{wxDbTable}}\label{wxdbtable}
2090
2091 A wxDbTable instance provides re-usable access to rows of data in
2092 a table contained within the associated ODBC datasource
2093
2094 See the \helpref{database classes overview}{odbcoverview} for
2095 an introduction to using the ODBC classes.
2096
2097 \wxheading{Include files}
2098
2099 <wx/dbtable.h>\\
2100 <wx/db.h>
2101 \wxheading{Library}
2102
2103 \helpref{wxOdbc}{librarieslist}
2104
2105
2106 \latexignore{\rtfignore{\wxheading{Members}}}
2107 \wxheading{Helper classes and data structures}
2108
2109 The following classes and structs are defined in dbtable.cpp/.h for use
2110 with the wxDbTable class.
2111
2112 \begin{itemize}\itemsep=0pt
2113 \item \helpref{wxDbColDef}{wxdbcoldef}
2114 \item \helpref{wxDbColDataPtr}{wxdbcoldataptr}
2115 \item \helpref{wxDbIdxDef}{wxdbidxdef}
2116 \end{itemize}
2117
2118 \wxheading{Constants}
2119
2120 \begin{verbatim}
2121     wxDB_DEFAULT_CURSOR  Primary cursor normally used for cursor based
2122                          operations.
2123
2124     wxDB_QUERY_ONLY      Used to indicate whether a table that is opened
2125                          is for query only, or if insert/update/deletes
2126                          will be performed on the table.  Less overhead
2127                          (cursors and memory) are allocated for query
2128                          only tables, plus read access times are faster
2129                          with some datasources.
2130
2131     wxDB_ROWID_LEN       [Oracle only] - Used when CanUpdateByRowID()
2132                          is true.  Optimizes updates so they are faster
2133                          by updating on the Oracle-specific ROWID column
2134                          rather than some other index.
2135
2136
2137     wxDB_DISABLE_VIEW    Use to indicate when a database view should not
2138                          be if a table is normally set up to use a view.
2139                          [Currently unsupported.]
2140
2141 \end{verbatim}
2142
2143
2144 \latexignore{\rtfignore{\wxheading{Members}}}
2145
2146 \membersection{wxDbTable::wxDbTable}\label{wxdbtableconstr}
2147
2148 \func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const wxString \&}{tblName},
2149   \param{const UWORD }{numColumns}, \param{const wxString \&}{qryTblName = ""},
2150   \param{bool }{qryOnly = !wxDB\_QUERY\_ONLY}, \param{const wxString \&}{tblPath = ""}}
2151
2152 Default constructor.
2153
2154 \wxheading{Parameters}
2155
2156 \docparam{pwxDb}{Pointer to the wxDb instance to be used by this wxDbTable
2157 instance.}
2158 \docparam{tblName}{The name of the table in the RDBMS.}
2159 \docparam{numColumns}{The number of columns in the table.  (Do NOT include the ROWID
2160 column in the count if using Oracle).}
2161 \docparam{qryTblName}{{\it OPTIONAL}.  The name of the table or view to base
2162 your queries on.  This argument allows you to specify a table/view other than
2163 the base table for this object to base your queries on.  This allows you to
2164 query on a view for example, but all of the INSERT, UPDATE and DELETES will
2165 still be performed on the base table for this wxDbTable object.  Basing your
2166 queries on a view can provide a substantial performance increase in cases where
2167 your queries involve many tables with multiple joins.  Default is "".}
2168 \docparam{qryOnly}{{\it OPTIONAL}.  Indicates whether the table will be
2169 accessible for query purposes only, or should the table create the necessary
2170 cursors to be able to insert, update, and delete data from the table.
2171 Default is !wxDB\_QUERY\_ONLY.}
2172 \docparam{tblPath}{{\it OPTIONAL}.  Some datasources (such as dBase)
2173 require a path to where the table is stored on the system.  Default is "".}
2174
2175 \membersection{wxDbTable::wxDbTable}\label{wxdbtabledestr}
2176
2177 \func{virtual}{\destruct{wxDbTable}}{}
2178
2179 Virtual default destructor.
2180
2181 \membersection{wxDbTable::BuildDeleteStmt}\label{wxdbtablebuilddeletestmt}
2182
2183 \func{void}{BuildDeleteStmt}{\param{wxString \&}{pSqlStmt},
2184 \param{int }{typeOfDel}, \param{const wxString \&}{pWhereClause=""}}
2185
2186 Constructs the full SQL statement that can be used to delete all rows matching
2187 the criteria in the pWhereClause.
2188
2189 \wxheading{Parameters}
2190
2191 \docparam{pSqlStmt}{Pointer to buffer for the SQL statement retrieved.  To be
2192 sure you have adequate space allocated for the SQL statement, allocate
2193 DB\_MAX\_STATEMENT\_LEN bytes.}
2194 \docparam{typeOfDel}{The type of delete statement being performed.  Can be one
2195 of three values: DB\_DEL\_KEYFIELDS, DB\_DEL\_WHERE or DB\_DEL\_MATCHING}
2196 \docparam{pWhereClause}{{\it OPTIONAL}.  If the typeOfDel is DB\_DEL\_WHERE,
2197 then you must also pass in a SQL WHERE clause in this argument.  Default
2198 is "".}
2199
2200 \wxheading{Remarks}
2201
2202 This member function constructs a SQL DELETE statement.  This can be used for
2203 debugging purposes if you are having problems executing your SQL statement.
2204
2205 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2206 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2207 this function.
2208
2209 \membersection{wxDbTable::BuildSelectStmt}\label{wxdbtablebuildselectstmt}
2210
2211 \func{void}{BuildSelectStmt}{\param{wxString \&}{pSqlStmt},
2212 \param{int }{typeOfSelect}, \param{bool }{distinct}}
2213
2214 Constructs the full SQL statement that can be used to select all rows matching
2215 the criteria in the pWhereClause.  This function is called internally in the
2216 wxDbTable class whenever the function \helpref{wxDbTable::Query}{wxdbtablequery}
2217 is called.
2218
2219 NOTE: Only the columns specified in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
2220 statements are included in the list of columns returned by the SQL statement
2221 created by a call to this function.
2222
2223 \wxheading{Parameters}
2224
2225 \docparam{pSqlStmt}{Pointer to storage for the SQL statement retrieved.  To be
2226 sure you have adequate space allocated for the SQL statement, allocate
2227 DB\_MAX\_STATEMENT\_LEN bytes.}
2228 \docparam{typeOfSelect}{The type of select statement being performed.  Can be
2229 one of four values: DB\_SELECT\_KEYFIELDS, DB\_SELECT\_WHERE, DB\_SELECT\_MATCHING
2230 or DB\_SELECT\_STATEMENT.}
2231 \docparam{distinct}{Whether to select distinct records only.}
2232
2233 \wxheading{Remarks}
2234
2235 This member function constructs a SQL SELECT statement.  This can be used for
2236 debugging purposes if you are having problems executing your SQL statement.
2237
2238 WHERE and FROM clauses specified using
2239 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2240 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2241 this function.
2242
2243 \membersection{wxDbTable::BuildUpdateStmt}\label{wxdbtablebuildupdatestmt}
2244
2245 \func{void}{BuildUpdateStmt}{\param{wxString \&}{pSqlStmt}, \param{int }{typeOfUpd},
2246 \param{const wxString \&}{pWhereClause=""}}
2247
2248 Constructs the full SQL statement that can be used to update all rows matching
2249 the criteria in the pWhereClause.
2250
2251 If typeOfUpdate is DB\_UPD\_KEYFIELDS, then the current values in the bound columns
2252 are used to determine which row(s) in the table are to be updated. The
2253 exception to this is when a datasource supports ROW IDs (Oracle).  The ROW ID
2254 column is used for efficiency purposes when available.
2255
2256 NOTE: Only the columns specified in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
2257 statements are included in the list of columns updated by the SQL statement
2258 created by a call to this function.  Any column definitions that were defined
2259 as being non-updateable will be excluded from the SQL UPDATE statement created
2260 by this function.
2261
2262 \wxheading{Parameters}
2263
2264 \docparam{pSqlStmt}{Pointer to storage for the SQL statement retrieved.  To be
2265 sure you have adequate space allocated for the SQL statement, allocate
2266 DB\_MAX\_STATEMENT\_LEN bytes.}
2267 \docparam{typeOfUpdate}{The type of update statement being performed.  Can be one
2268 of two values: DB\_UPD\_KEYFIELDS or DB\_UPD\_WHERE.}
2269 \docparam{pWhereClause}{{\it OPTIONAL}.  If the typeOfUpdate is DB\_UPD\_WHERE,
2270 then you must also pass in a SQL WHERE clause in this argument. Default is "".}
2271
2272 \wxheading{Remarks}
2273
2274 This member function allows you to see what the SQL UPDATE statement looks like
2275 that the ODBC class library builds.  This can be used for debugging purposes if
2276 you are having problems executing your SQL statement.
2277
2278 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2279 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2280 this function.
2281
2282
2283 \membersection{wxDbTable::BuildWhereClause}\label{wxdbtablebuildwhereclause}
2284
2285 \func{void}{BuildWhereClause}{\param{wxString \&}{pWhereClause},
2286 \param{int }{typeOfWhere}, \param{const wxString \&}{qualTableName=""},
2287 \param{bool }{useLikeComparison=false}}
2288
2289 Constructs the portion of a SQL statement which would follow the word 'WHERE'
2290 in a SQL statement to be passed to the datasource.  The returned string
2291 does NOT include the word 'WHERE'.
2292
2293 \wxheading{Parameters}
2294
2295 \docparam{pWhereClause}{Pointer to storage for the SQL statement retrieved.
2296 To be sure you have adequate space allocated for the SQL statement, allocate
2297 DB\_MAX\_STATEMENT\_LEN bytes.}
2298 \docparam{typeOfWhere}{The type of where clause to generate.  Can be one of
2299 two values:  DB\_WHERE\_KEYFIELDS or DB\_WHERE\_MATCHING.}
2300 \docparam{qualTableName}{{\it OPTIONAL}.  Prepended to all base table
2301 column names.  For use when a FROM clause has been specified with the
2302 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause},
2303 to clarify which table a column name reference belongs to.  Default is "".}
2304 \docparam{useLikeComparison}{{\it OPTIONAL}.  Should the constructed WHERE
2305 clause utilize the LIKE comparison operator.  If false, then the '='
2306 operator is used.  Default is false.}
2307
2308 \wxheading{Remarks}
2309
2310 This member function allows you to see what the SQL WHERE clause looks like
2311 that the ODBC class library builds.  This can be used for debugging purposes
2312 if you are having problems executing your own SQL statements.
2313
2314 If using 'typeOfWhere' set to DB\_WHERE\_MATCHING, any bound columns currently
2315 containing a NULL value are not included in the WHERE clause's list of
2316 columns to use in the comparison.
2317
2318
2319 \membersection{wxDbTable::CanSelectForUpdate}\label{wxdbtablecanselectforupdate}
2320
2321 \func{bool}{CanSelectForUpdate}{\void}
2322
2323 Use this function to determine if the datasource supports SELECT ... FOR UPDATE.
2324 When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement,
2325 all records {\it retrieved} (not just queried, but actually retrieved using
2326 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}, etc) from the result set are
2327 locked.
2328
2329 \wxheading{Remarks}
2330
2331 Not all datasources support the "FOR UPDATE" clause, so you must use this
2332 member function to determine if the datasource currently connected to supports
2333 this behavior or not before trying to select using "FOR UPDATE".
2334
2335 If the wxDbTable instance was created with the parameter wxDB\_QUERY\_ONLY, then
2336 this function will return false.  For all known databases which do not support
2337 the FOR UPDATE clause, this function will return false also.
2338
2339 \membersection{wxDbTable::CanUpdateByROWID}\label{wxdbtablecanupdatebyrowid}
2340
2341 \func{bool}{CanUpdateByROWID}{\void}
2342
2343 CURRENTLY ONLY POSSIBLE IF USING ORACLE.
2344
2345 --- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV 1 2000 - gt
2346
2347 Every Oracle table has a hidden column named ROWID.  This is a pointer to the
2348 physical location of the record in the datasource and allows for very fast
2349 updates and deletes.  The key is to retrieve this ROWID during your query so
2350 it is available during an update or delete operation.
2351
2352 Use of the ROWID feature is always handled by the class library except in the
2353 case of \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.  Since
2354 you are passing in the SQL SELECT statement,
2355 it is up to you to include the ROWID column in your query.  If you do not,
2356 the application will still work, but may not be as optimized.  The ROWID is
2357 always the last column in the column list in your SQL SELECT statement.
2358 The ROWID is not a column in the normal sense and should not be considered
2359 part of the column definitions for the wxDbTable object.
2360
2361 \wxheading{Remarks}
2362
2363 The decision to include the ROWID in your SQL SELECT statement must be
2364 deferred until runtime since it depends on whether you are connected
2365 to an Oracle datasource or not.
2366
2367 \wxheading{Example}
2368
2369 \begin{verbatim}
2370     // Incomplete code sample
2371     wxDbTable parts;
2372     .....
2373     if (parts.CanUpdateByROWID())
2374     {
2375         // Note that the ROWID column must always be the last column selected
2376         sqlStmt = "SELECT PART_NUM, PART_DESC, ROWID" FROM PARTS";
2377     }
2378     else
2379         sqlStmt = "SELECT PART_NUM, PART_DESC FROM PARTS";
2380 \end{verbatim}
2381
2382
2383 \membersection{wxDbTable::ClearMemberVar}\label{wxdbtableclearmembervar}
2384
2385 \func{void}{ClearMemberVar}{\param{UWORD }{colNumber}, \param{bool }{setToNull=false}}
2386
2387 Same as \helpref{wxDbTable::ClearMemberVars}{wxdbtableclearmembervars} except
2388 that this function clears only the specified column of its values, and
2389 optionally sets the column to be a NULL column.
2390
2391 \docparam{colNumber}{Column number that is to be cleared.  This number (between 0
2392 and (numColumns-1)) is the index of the column definition created using the
2393 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} function.}
2394 \docparam{setToNull}{{\it OPTIONAL}.  Indicates whether the column should be
2395 flagged as being a NULL value stored in the bound memory variable.  If true,
2396 then any value stored in the bound member variable is cleared.  Default is
2397 false.}
2398
2399 \membersection{wxDbTable::ClearMemberVars}\label{wxdbtableclearmembervars}
2400
2401 \func{void}{ClearMemberVars}{\param{bool }{setToNull=false}}
2402
2403 Initializes all bound columns of the wxDbTable instance to zero.  In the case
2404 of a string, zero is copied to the first byte of the string.
2405
2406 \docparam{setToNull}{{\it OPTIONAL}.  Indicates whether all columns should be
2407 flagged as having a NULL value stored in the bound memory variable.  If true,
2408 then any value stored in the bound member variable is cleared.  Default is
2409 false.}
2410
2411 \wxheading{Remarks}
2412
2413 This is useful before calling functions such as
2414 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2415 \helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching} since these
2416 functions build their WHERE clauses from non-zero columns.  To call either
2417 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2418 \helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching} use this sequence:
2419
2420 \begin{verbatim}
2421 1)  ClearMemberVars()
2422 2)  Assign columns values you wish to match on
2423 3)  Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
2424 \end{verbatim}
2425
2426 \membersection{wxDbTable::CloseCursor}\label{wxdbtableclosecursor}
2427
2428 \func{bool}{CloseCursor}{\param{HSTMT}{cursor}}
2429
2430 Closes the specified cursor associated with the wxDbTable object.
2431
2432 \wxheading{Parameters}
2433
2434 \docparam{cursor}{The cursor to be closed.}
2435
2436 \wxheading{Remarks}
2437
2438 Typically handled internally by the ODBC class library, but may be used by the
2439 programmer if desired.
2440
2441 \normalbox{DO NOT CLOSE THE wxDB\_DEFAULT\_CURSOR!}
2442
2443 \membersection{wxDbTable::Count}\label{wxdbtablecount}
2444
2445 \func{ULONG }{Count}{\param{const wxString \&}{args="*"}}
2446
2447 Returns the number of records which would be in the result set using the
2448 current query parameters specified in the WHERE and FROM clauses.
2449
2450 \wxheading{Parameters}
2451
2452 \docparam{args}{{\it OPTIONAL}.  This argument allows the use of the
2453 DISTINCT keyword against a column name to cause the returned count to
2454 only indicate the number of rows in the result set that have a unique
2455 value in the specified column.  An example is shown below.  Default is "*",
2456 meaning a count of the total number of rows matching is returned, regardless
2457 of uniqueness.}
2458
2459 \wxheading{Remarks}
2460
2461 This function can be called before or after an actual query to obtain the
2462 count of records in the result set.  Count() uses its own cursor, so result
2463 set cursor positioning is not affected by calls to Count().
2464
2465 WHERE and FROM clauses specified using
2466 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2467 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} ARE used by
2468 this function.
2469
2470 \wxheading{Example}
2471
2472 \begin{verbatim}
2473
2474     USERS TABLE
2475
2476     FIRST_NAME      LAST_NAME
2477     -----------     ----------
2478     John            Doe
2479     Richard         Smith
2480     Michael         Jones
2481     John            Carpenter
2482
2483     // Incomplete code sample
2484     wxDbTable users;
2485     .....
2486     users.SetWhereClause("");
2487
2488     // This Count() will return 4, as there are four users listed above
2489     // that match the query parameters
2490     totalNumberOfUsers = users.Count();
2491
2492     // This Count() will return 3, as there are only 3 unique first names
2493     // in the table above - John, Richard, Michael.
2494     totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
2495 \end{verbatim}
2496
2497 \membersection{wxDbTable::CreateIndex}\label{wxdbtablecreateindex}
2498
2499 \func{bool}{CreateIndex}{\param{const wxString \&}{IndexName}, \param{bool }{unique},
2500 \param{UWORD }{numIndexColumns}, \param{wxDbIdxDef *}{pIndexDefs},
2501 \param{bool }{attemptDrop=true}}
2502
2503 This member function allows you to create secondary (non-primary) indexes on
2504 your tables.  You first create your table, normally specifying a primary
2505 index, and then create any secondary indexes on the table.  Indexes in
2506 relational model are not required.  You do not need indexes to look up records
2507 in a table or to join two tables together.  In the relational model, indexes,
2508 if available, provide a quicker means to look up data in a table.  To enjoy
2509 the performance benefits of indexes, the indexes must be defined on the
2510 appropriate columns and your SQL code must be written in such a way as to
2511 take advantage of those indexes.
2512
2513 \wxheading{Parameters}
2514
2515 \docparam{IndexName}{Name of the Index.  Name must be unique within the table
2516 space of the datasource.}
2517 \docparam{unique}{Indicates if this index is unique.}
2518 \docparam{numIndexColumns}{Number of columns in the index.}
2519 \docparam{pIndexDefs}{A pointer to an array \helpref{wxDbIdxDef}{wxdbidxdef} structures. }
2520 \docparam{attemptDrop}{{\it OPTIONAL}.  Indicates if the function should try
2521 to execute a \helpref{wxDbTable::DropIndex}{wxdbtabledropindex} on the index
2522 name provided before trying to create the index name.  Default is true.}
2523
2524 \wxheading{Remarks}
2525
2526 The first parameter, index name, must be unique and should be given a
2527 meaningful name.  Common practice is to include the table name as a prefix
2528 in the index name (e.g. For table PARTS, you might want to call your index
2529 PARTS\_Index1).  This will allow you to easily view all
2530 of the indexes defined for a given table grouped together alphabetically.
2531
2532 The second parameter indicates if the index is unique or not.  Uniqueness
2533 is enforced at the RDBMS level preventing rows which would have duplicate
2534 indexes from being inserted into the table when violating a unique index's
2535 uniqueness.
2536
2537 In the third parameter, specify how many columns are in your index.  This
2538 number must match the number of columns defined in the 'pIndexDefs' parameter.
2539
2540 The fourth parameter specifies which columns make up the index using the
2541 \helpref{wxDbIdxDef}{wxdbidxdef} structure.  For each column in the index, you must specify two
2542 things, the column name and the sort order (ascending / descending).  See
2543 the example below to see how to build and pass in the \helpref{wxDbIdxDef}{wxdbidxdef} structure.
2544
2545 The fifth parameter is provided to handle the differences in datasources as
2546 to whether they will automatically overwrite existing indexes with the same
2547 name or not.  Some datasources require that the existing index must be dropped
2548 first, so this is the default behavior.
2549
2550 Some datasources (MySQL, and possibly others) require columns which are to be
2551 part of an index to be defined as NOT NULL.  When this function is called, if
2552 a column is not defined to be NOT NULL, a call to this function will modify
2553 the column definition to change any columns included in the index to be
2554 NOT NULL.  In this situation, if a NULL value already exists in one of the
2555 columns that is being modified, creation of the index will fail.
2556
2557 PostGres is unable to handle index definitions which specify whether the index
2558 is ascending or descending, and defaults to the system default when the index
2559 is created.
2560
2561 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2562 after executing this function.
2563
2564 \wxheading{Example}
2565
2566 \begin{verbatim}
2567     // Create a secondary index on the PARTS table
2568     wxDbIdxDef  IndexDef[2];  // 2 columns make up the index
2569
2570     wxStrcpy(IndexDef[0].ColName, "PART_DESC");  // Column 1
2571     IndexDef[0].Ascending = true;
2572
2573     wxStrcpy(IndexDef[1].ColName, "SERIAL_NO");  // Column 2
2574     IndexDef[1].Ascending = false;
2575
2576     // Create a name for the index based on the table's name
2577     wxString indexName;
2578     indexName.Printf("%s_Index1",parts->GetTableName());
2579     parts->CreateIndex(indexName, true, 2, IndexDef);
2580 \end{verbatim}
2581
2582 \membersection{wxDbTable::CreateTable}\label{wxdbtablecreatetable}
2583
2584 \func{bool}{CreateTable}{\param{bool }{attemptDrop=true}}
2585
2586 Creates a table based on the definitions previously defined for this
2587 wxDbTable instance.
2588
2589 \wxheading{Parameters}
2590
2591 \docparam{attemptDrop}{{\it OPTIONAL}.  Indicates whether the driver should
2592 attempt to drop the table before trying to create it.  Some datasources will
2593 not allow creation of a table if the table already exists in the table space
2594 being used.  Default is true.}
2595
2596 \wxheading{Remarks}
2597
2598 This function creates the table and primary index (if any) in the table space
2599 associated with the connected datasource.  The owner of these objects will
2600 be the user id that was given when \helpref{wxDb::Open}{wxdbopen} was called.
2601 The objects will be created in the default schema/table space for that user.
2602
2603 In your derived wxDbTable object constructor, the columns and primary index
2604 of the table are described through the \helpref{wxDbColDef}{wxdbcoldef} structure.
2605 \helpref{wxDbTable::CreateTable}{wxdbtablecreatetable} uses this information
2606 to create the table and to add the primary index.  See
2607 \helpref{wxDbTable}{wxdbtable} ctor and wxDbColDef description for additional
2608 information on describing the columns of the table.
2609
2610 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2611 after executing this function.
2612
2613 \membersection{wxDbTable::DB\_STATUS}\label{wxdbtabledbstatus}
2614
2615 \func{bool}{DB\_STATUS}{\void}
2616
2617 Accessor function that returns the wxDb private member variable DB\_STATUS for
2618 the database connection used by this instance of wxDbTable.
2619
2620 \membersection{wxDbTable::Delete}\label{wxdbtabledelete}
2621
2622 \func{bool}{Delete}{\void}
2623
2624 Deletes the row from the table indicated by the current cursor.
2625
2626 \wxheading{Remarks}
2627
2628 Use \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst},
2629 \helpref{wxDbTable::GetLast}{wxdbtablegetlast},
2630 \helpref{wxDbTable::GetNext}{wxdbtablegetnext} or
2631 \helpref{wxDbTable::GetPrev}{wxdbtablegetprev} to position the cursor to
2632 a valid record.  Once positioned on a record, call this function to delete
2633 the row from the table.
2634
2635 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2636 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
2637 this function to commit or rollback the deletion.
2638
2639 NOTE: Most datasources have a limited size "rollback" segment.  This means
2640 that it is only possible to insert/update/delete a finite number of rows
2641 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2642 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2643 segment varies from database to database, and is user configurable in
2644 most databases.  Therefore it is usually best to try to perform a commit
2645 or rollback at relatively small intervals when processing a larger number
2646 of actions that insert/update/delete rows in a table.
2647
2648 \membersection{wxDbTable::DeleteCursor}\label{wxdbtabledeletecursor}
2649
2650 \func{bool}{DeleteCursor}{\param{HSTMT *}{hstmtDel}}
2651
2652 Allows a program to delete a cursor.
2653
2654 \wxheading{Parameters}
2655
2656 \docparam{hstmtDel}{Handle of the cursor to delete.}
2657
2658 \wxheading{Remarks}
2659
2660 For default cursors associated with the instance of wxDbTable, it is not
2661 necessary to specifically delete the cursors.  This is automatically done
2662 in the wxDbTable destructor.
2663
2664 NOTE: If the cursor could not be deleted for some reason, an error is logged
2665 indicating the reason.  Even if the cursor could not be deleted, the HSTMT
2666 that is passed in is deleted, and the pointer is set to NULL.
2667
2668 \normalbox{DO NOT DELETE THE wxDB\_DEFAULT\_CURSOR!}
2669
2670 \membersection{wxDbTable::DeleteMatching}\label{wxdbtabledeletematching}
2671
2672 \func{bool}{DeleteMatching}{\void}
2673
2674 This member function allows you to delete records from your wxDbTable object
2675 by specifying the data in the columns to match on.
2676
2677 \wxheading{Remarks}
2678
2679 To delete all users with a first name of "JOHN", do the following:
2680
2681 \begin{enumerate}\itemsep=0pt
2682 \item Clear all "columns" using wxDbTable::ClearMemberVars().
2683 \item Set the FIRST\_NAME column equal to "JOHN".
2684 \item Call wxDbTable::DeleteMatching().
2685 \end{enumerate}
2686
2687 The WHERE clause is built by the ODBC class library based on all non-NULL
2688 columns.  This allows deletion of records by matching on any column(s) in
2689 your wxDbTable instance, without having to write the SQL WHERE clause.
2690
2691 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2692 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
2693 this function to commit or rollback the deletion.
2694
2695 NOTE: Row(s) should be locked before deleting them to make sure they are
2696 not already in use.  This can be achieved by calling
2697 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching},
2698 and then retrieving the records, locking each as you go (assuming FOR UPDATE
2699 is allowed on the datasource).  After the row(s) have been successfully locked,
2700 call this function.
2701
2702 NOTE: Most datasources have a limited "rollback" segment.  This means
2703 that it is only possible to insert/update/delete a finite number of rows
2704 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2705 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2706 segment varies from database to database, and is user configurable in
2707 most databases.  Therefore it is usually best to try to perform a commit
2708 or rollback at relatively small intervals when processing a larger number
2709 of actions that insert/update/delete rows in a table.
2710
2711 \wxheading{Example}
2712
2713 \begin{verbatim}
2714     // Incomplete code sample to delete all users with a first name
2715     // of "JOHN"
2716     users.ClearMemberVars();
2717     wxStrcpy(users.FirstName,"JOHN");
2718     users.DeleteMatching();
2719 \end{verbatim}
2720
2721
2722 \membersection{wxDbTable::DeleteWhere}\label{wxdbtabledeletewhere}
2723
2724 \func{bool}{DeleteWhere}{\param{const wxString \&}{pWhereClause}}
2725
2726 Deletes all rows from the table which match the criteria specified in the
2727 WHERE clause that is passed in.
2728
2729 \wxheading{Parameters}
2730
2731 \docparam{pWhereClause}{SQL WHERE clause.  This WHERE clause determines which
2732 records will be deleted from the table interfaced through the wxDbTable
2733 instance.  The WHERE clause passed in must be compliant with the SQL 92
2734 grammar.  Do not include the keyword 'WHERE'
2735 }
2736
2737 \wxheading{Remarks}
2738
2739 This is the most powerful form of the wxDbTable delete functions.  This
2740 function gives access to the full power of SQL.  This function can be used
2741 to delete records by passing a valid SQL WHERE clause.  Sophisticated
2742 deletions can be performed based on multiple criteria using the full
2743 functionality of the SQL language.
2744
2745 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} must be called after use of
2746 this function to commit the deletions.
2747
2748 Note: This function is limited to deleting records from the table associated
2749 with this wxDbTable object only.  Deletions on joined tables is not possible.
2750
2751 NOTE: Most datasources have a limited size "rollback" segment.  This means
2752 that it is only possible to insert/update/delete a finite number of rows
2753 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2754 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2755 segment varies from database to database, and is user configurable in
2756 most databases.  Therefore it is usually best to try to perform a commit
2757 or rollback at relatively small intervals when processing a larger number
2758 of actions that insert/update/delete rows in a table.
2759
2760 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2761 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2762 this function.
2763
2764 \wxheading{Example}
2765
2766 \begin{verbatim}
2767     // Delete parts 1 thru 10 from containers 'X', 'Y' and 'Z' that
2768     // are magenta in color
2769     parts.DeleteWhere("(PART_NUMBER BETWEEN 1 AND 10) AND \
2770                         CONTAINER IN ('X', 'Y', 'Z') AND \
2771                         UPPER(COLOR) = 'MAGENTA'");
2772 \end{verbatim}
2773
2774
2775 \membersection{wxDbTable::DropIndex}\label{wxdbtabledropindex}
2776
2777 \func{bool}{DropIndex}{\param{const wxString \&}{IndexName}}
2778
2779 Allows an index on the associated table to be dropped (deleted) if the user
2780 login has sufficient privileges to do so.
2781
2782 \wxheading{Parameters}
2783
2784 \docparam{IndexName}{Name of the index to be dropped.}
2785
2786 \wxheading{Remarks}
2787
2788 If the index specified in the 'IndexName' parameter does not exist, an error
2789 will be logged, and the function will return a result of false.
2790
2791 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2792 after executing this function.
2793
2794 \membersection{wxDbTable::DropTable}\label{wxdbtabledroptable}
2795
2796 \func{bool}{DropTable}{\void}
2797
2798 Deletes the associated table if the user has sufficient privileges to do so.
2799
2800 \wxheading{Remarks}
2801
2802 This function returns true if the table does not exist, but only for
2803 supported databases (see \helpref{wxDb::Dbms}{wxdbdbms}).  If a datasource
2804 is not specifically supported, and this function is called, the function
2805 will return false.
2806
2807 Most datasources/ODBC drivers will delete any indexes associated with the
2808 table automatically, and others may not.  Check the documentation for your
2809 database to determine the behavior.
2810
2811 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2812 after executing this function.
2813
2814 \membersection{wxDbTable::From}\label{wxdbtablefrom}
2815
2816 \func{const wxString \&}{From}{}
2817
2818 \func{void}{From}{\param{const wxString \&}{From}}
2819
2820 Accessor function for the private class member wxDbTable::from.  Can be used
2821 as a synonym for \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
2822 (the first form of this function) or
2823 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} (the second form
2824 of this function).
2825
2826 \wxheading{Parameters}
2827
2828 \docparam{From}{A comma separated list of table names that are to be inner
2829 joined with the base table's columns so that the joined table's columns
2830 may be returned in the result set or used as a portion of a comparison with
2831 the base table's columns.  NOTE that the base tables name must NOT be included
2832 in the FROM clause, as it is automatically included by the wxDbTable class
2833 in constructing query statements.}
2834
2835 \wxheading{Return value}
2836
2837 The first form of this function returns the current value of the wxDbTable
2838 member variable ::from.
2839
2840 The second form of the function has no return value, as it will always set
2841 the from clause successfully.
2842
2843 \wxheading{See also}
2844
2845 \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause},
2846 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
2847
2848
2849 \membersection{wxDbTable::GetColDefs}\label{wxdbtablegetcoldefs}
2850
2851 \func{wxDbColDef *}{GetColDefs}{}
2852
2853 Accessor function that returns a pointer to the array of column definitions
2854 that are bound to the columns that this wxDbTable instance is associated
2855 with.
2856
2857 To determine the number of elements pointed to by the returned
2858 \helpref{wxDbColDef}{wxdbcoldef} pointer, use the
2859 \helpref{wxDbTable::GetNumberOfColumns}{wxdbtablegetnumberofcolumns} function.
2860
2861 \wxheading{Remarks}
2862
2863 These column definitions must not be manually redefined after they have been
2864 set.
2865
2866 \membersection{wxDbTable::GetCursor}\label{wxdbtablegetcursor}
2867
2868 \func{HSTMT}{GetCursor}{\void}
2869
2870 Returns the HSTMT value of the current cursor for this wxDbTable object.
2871
2872 \wxheading{Remarks}
2873
2874 This function is typically used just before changing to use a different cursor
2875 so that after the program is finished using the other cursor, the current
2876 cursor can be set back to being the cursor in use.
2877
2878 \wxheading{See also}
2879
2880 \helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}, \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor}
2881
2882 \membersection{wxDbTable::GetDb}\label{wxdbtablegetdb}
2883
2884 \func{wxDb *}{GetDb}{}
2885
2886 Accessor function for the private member variable pDb which is a pointer to
2887 the datasource connection that this wxDbTable instance uses.
2888
2889 \membersection{wxDbTable::GetFirst}\label{wxdbtablegetfirst}
2890
2891 \func{bool}{GetFirst}{\void}
2892
2893 Retrieves the FIRST row in the record set as defined by the current query.
2894 Before retrieving records, a query must be performed using
2895 \helpref{wxDbTable::Query}{wxdbtablequery},
2896 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2897 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2898 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2899
2900 \wxheading{Remarks}
2901
2902 This function can only be used if the datasource connection used by the
2903 wxDbTable instance was created with FwdOnlyCursors set to false.  If the
2904 connection does not allow backward scrolling cursors, this function will
2905 return false, and the data contained in the bound columns will be undefined.
2906
2907 \wxheading{See also}
2908
2909 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
2910
2911 \membersection{wxDbTable::GetFromClause}\label{wxdbtablegetfromclause}
2912
2913 \func{const wxString \&}{GetFromClause}{}
2914
2915 Accessor function that returns the current FROM setting assigned with the
2916 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
2917
2918 \wxheading{See also}
2919
2920 \helpref{wxDbTable::From}{wxdbtablefrom}
2921
2922 \membersection{wxDbTable::GetLast}\label{wxdbtablegetlast}
2923
2924 \func{bool}{GetLast}{\void}
2925
2926 Retrieves the LAST row in the record set as defined by the current query.
2927 Before retrieving records, a query must be performed using
2928 \helpref{wxDbTable::Query}{wxdbtablequery},
2929 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2930 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2931 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2932
2933 \wxheading{Remarks}
2934
2935 This function can only be used if the datasource connection used by the
2936 wxDbTable instance was created with FwdOnlyCursors set to false.  If the
2937 connection does not allow backward scrolling cursors, this function will
2938 return false, and the data contained in the bound columns will be undefined.
2939
2940 \wxheading{See also}
2941
2942 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
2943
2944 \membersection{wxDbTable::GetNewCursor}\label{wxdbtablegetnewcursor}
2945
2946 \func{HSTMT *}{GetNewCursor}{\param{bool }{setCursor=false},
2947 \param{bool }{bindColumns=true}}
2948
2949 This function will create a new cursor that can be used to access the table
2950 being referenced by this wxDbTable instance, or to execute direct SQL commands
2951 on without affecting the cursors that are already defined and possibly
2952 positioned.
2953
2954 \wxheading{Parameters}
2955
2956 \docparam{setCursor}{{\it OPTIONAL}.  Should this new cursor be set to be the
2957 current cursor after successfully creating the new cursor.  Default is false.}
2958 \docparam{bindColumns}{{\it OPTIONAL}.  Should this new cursor be bound to all
2959 the memory variables that the default cursor is bound to.  Default is true.}
2960
2961 \wxheading{Remarks}
2962
2963 This new cursor must be closed using
2964 \helpref{wxDbTable::DeleteCursor}{wxdbtabledeletecursor}
2965 by the calling program before the wxDbTable instance is deleted, or both
2966 memory and resource leaks will occur.
2967
2968 \membersection{wxDbTable::GetNext}\label{wxdbtablegetnext}
2969
2970 \func{bool}{GetNext}{\void}
2971
2972 Retrieves the NEXT row in the record set after the current cursor position
2973 as defined by the current query.  Before retrieving records, a query must be
2974 performed using \helpref{wxDbTable::Query}{wxdbtablequery},
2975 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2976 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2977 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2978
2979 \wxheading{Return value}
2980
2981 This function returns false when the current cursor has reached the end of
2982 the result set.  When false is returned, data in the bound columns is
2983 undefined.
2984
2985 \wxheading{Remarks}
2986
2987 This function works with both forward and backward scrolling cursors.
2988
2989 \wxheading{See also}
2990 \helpref{wxDbTable::++}{wxdbtableplusplus}
2991
2992 \membersection{wxDbTable::GetNumberOfColumns}\label{wxdbtablegetnumberofcolumns}
2993
2994 \func{UWORD }{GetNumberOfColumns}{}
2995
2996 Accessor function that returns the number of columns that are statically
2997 bound for access by the wxDbTable instance.
2998
2999 \membersection{wxDbTable::GetOrderByClause}\label{wxdbtablegetorderbyclause}
3000
3001 \func{const wxString \&}{GetOrderByClause}{}
3002
3003 Accessor function that returns the current ORDER BY setting assigned with
3004 the \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}.
3005
3006 \wxheading{See also}
3007
3008 \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
3009
3010 \membersection{wxDbTable::GetPrev}\label{wxdbtablegetprev}
3011
3012 \func{bool}{GetPrev}{\void}
3013
3014 Retrieves the PREVIOUS row in the record set before the current cursor
3015 position as defined by the current query.  Before retrieving records, a
3016 query must be performed using \helpref{wxDbTable::Query}{wxdbtablequery},
3017 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
3018 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
3019 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
3020
3021 \wxheading{Return value}
3022
3023 This function returns false when the current cursor has reached the beginning
3024 of the result set and there are now other rows prior to the cursors current
3025 position.  When false is returned, data in the bound columns is undefined.
3026
3027 \wxheading{Remarks}
3028
3029 This function can only be used if the datasource connection used by the
3030 wxDbTable instance was created with FwdOnlyCursors set to false.  If the
3031 connection does not allow backward scrolling cursors, this function will
3032 return false, and the data contained in the bound columns will be undefined.
3033
3034 \wxheading{See also}
3035
3036 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors},
3037 \helpref{wxDbTable::--}{wxdbtableminusminus}
3038
3039 \membersection{wxDbTable::GetQueryTableName}\label{wxdbtablegetquerytablename}
3040
3041 \func{const wxString \&}{GetQueryTableName}{}
3042
3043 Accessor function that returns the name of the table/view that was indicated
3044 as being the table/view to query against when this wxDbTable instance was
3045 created.
3046
3047 \wxheading{See also}
3048
3049 \helpref{wxDbTable constructor}{wxdbtableconstr}
3050
3051 \membersection{wxDbTable::GetRowNum}\label{wxdbtablegetrownum}
3052
3053 \func{UWORD}{GetRowNum}{\void}
3054
3055 Returns the ODBC row number for performing positioned updates and deletes.
3056
3057 \wxheading{Remarks}
3058
3059 This function is not being used within the ODBC class library and may be a
3060 candidate for removal if no use is found for it.
3061
3062 Row number with some datasources/ODBC drivers is the position in the result set,
3063 while in others it may be a physical position in the database.  Check your
3064 database documentation to find out which behavior is supported.
3065
3066 \membersection{wxDbTable::GetTableName}\label{wxdbtablegettablename}
3067
3068 \func{const wxString \&}{GetTableName}{}
3069
3070 Accessor function that returns the name of the table that was indicated
3071 as being the table that this wxDbTable instance was associated with.
3072
3073 \membersection{wxDbTable::GetTablePath}\label{wxdbtablegettablepath}
3074
3075 \func{const wxString \&}{GetTablePath}{}
3076
3077 Accessor function that returns the path to the data table that was indicated
3078 during creation of this wxDbTable instance.
3079
3080 \wxheading{Remarks}
3081
3082 Currently only applicable to dBase and MS-Access datasources.
3083
3084 \membersection{wxDbTable::GetWhereClause}\label{wxdbtablegetwhereclause}
3085
3086 \func{const wxString \&}{GetWhereClause}{}
3087
3088 Accessor function that returns the current WHERE setting assigned with the
3089 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3090
3091 \wxheading{See also}
3092
3093 \helpref{wxDbTable::Where}{wxdbtablewhere}
3094
3095 \membersection{wxDbTable::Insert}\label{wxdbtableinsert}
3096
3097 \func{int }{Insert}{\void}
3098
3099 Inserts a new record into the table being referenced by this wxDbTable
3100 instance.  The values in the member variables of the wxDbTable instance are
3101 inserted into the columns of the new row in the database.
3102
3103 \wxheading{Return value}
3104
3105 \begin{verbatim}
3106     DB_SUCCESS              Record inserted successfully (value = 1)
3107
3108     DB_FAILURE              Insert failed (value = 0)
3109
3110     DB_ERR_INTEGRITY_CONSTRAINT_VIOL
3111                             The insert failed due to an integrity
3112                             constraint violation (duplicate non-unique
3113                             index entry) is attempted.
3114 \end{verbatim}
3115
3116 \wxheading{Remarks}
3117
3118 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3119 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3120 this function to commit or rollback the insertion.
3121
3122 \wxheading{Example}
3123
3124 \begin{verbatim}
3125     // Incomplete code snippet
3126     wxStrcpy(parts->PartName, "10");
3127     wxStrcpy(parts->PartDesc, "Part #10");
3128     parts->Qty = 1000;
3129     RETCODE retcode = parts->Insert();
3130     switch(retcode)
3131     {
3132         case DB_SUCCESS:
3133             parts->GetDb()->CommitTrans();
3134             return(true);
3135         case DB_ERR_INTEGRITY_CONSTRAINT_VIOL:
3136             // Current data would result in a duplicate key
3137             // on one or more indexes that do not allow duplicates
3138             parts->GetDb()->RollbackTrans();
3139             return(false);
3140         default:
3141             // Insert failed for some unexpected reason
3142             parts->GetDb()->RollbackTrans();
3143             return(false);
3144     }
3145 \end{verbatim}
3146
3147 \membersection{wxDbTable::IsColNull}\label{wxdbtableiscolnull}
3148
3149 \func{bool }{IsColNull}{\param{UWORD }{colNumber}} const
3150
3151 Used primarily in the ODBC class library to determine if a column value is
3152 set to "NULL".  Works for all data types supported by the ODBC class library.
3153
3154 \wxheading{Parameters}
3155
3156 \docparam{colNumber}{The column number of the bound column as defined by the
3157 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
3158 calls which defined the columns accessible to this wxDbTable instance.}
3159
3160 \wxheading{Remarks}
3161
3162 NULL column support is currently not fully implemented as of wxWidgets 2.4.
3163
3164 \membersection{wxDbTable::IsCursorClosedOnCommit}\label{wxdbtableiscursorclosedoncommit}
3165
3166 \func{bool }{IsCursorClosedOnCommit}{\void}
3167
3168 Accessor function to return information collected during the opening of the
3169 datasource connection that is used by this wxDbTable instance.  The result
3170 returned by this function indicates whether an implicit closing of the cursor is
3171 done after a commit on the database connection.
3172
3173 \wxheading{Return value}
3174
3175 Returns true if the cursor associated with this wxDbTable object is closed
3176 after a commit or rollback operation.  Returns false otherwise.
3177
3178 \wxheading{Remarks}
3179
3180 If more than one wxDbTable instance used the same database connection, all cursors
3181 which use the database connection are closed on the commit if this function
3182 indicates true.
3183
3184 \membersection{wxDbTable::IsQueryOnly}\label{wxdbtableisqueryonly}
3185
3186 \func{bool }{IsQueryOnly}{}
3187
3188 Accessor function that returns a value indicating if this wxDbTable instance
3189 was created to allow only queries to be performed on the bound columns.  If
3190 this function returns true, then no actions may be performed using this
3191 wxDbTable instance that would modify (insert/delete/update) the table's data.
3192
3193 \membersection{wxDbTable::Open}\label{wxdbtableopen}
3194
3195 \func{bool }{Open}{\param{bool }{checkPrivileges=false}, \param{bool }{checkTableExists=true}}
3196
3197 Every wxDbTable instance must be opened before it can be used.  This function
3198 checks for the existence of the requested table, binds columns, creates required
3199 cursors, (insert/select and update if connection is not wxDB\_QUERY\_ONLY) and
3200 constructs the insert statement that is to be used for inserting data as a new
3201 row in the datasource.
3202
3203 NOTE: To retrieve data into an opened table, the of the table must be bound
3204 to the variables in the program via call(s) to
3205 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} before calling Open().
3206
3207 See the \helpref{database classes overview}{odbcoverview} for
3208 an introduction to using the ODBC classes.
3209
3210 \wxheading{Parameters}
3211
3212 \docparam{checkPrivileges}{Indicates whether the Open() function should check
3213 whether the current connected user has at least SELECT privileges to access the
3214 table to which they are trying to open.  Default is false.}
3215
3216 \docparam{checkTableExists}{Indicates whether the Open() function should check
3217 whether the table exists in the database or not before opening it.  Default is true.}
3218
3219 \wxheading{Remarks}
3220
3221 If the function returns a false value due to the table not existing, a log
3222 entry is recorded for the datasource connection indicating the problem
3223 that was detected when checking for table existence.  Note that it is usually
3224 best for the calling routine to check for the existence of the table and for
3225 sufficient user privileges to access the table in the mode (wxDB\_QUERY\_ONLY or
3226 !wxDB\_QUERY\_ONLY) before trying to open the table for the best possible
3227 explanation as to why a table cannot be opened.
3228
3229 Checking the user's privileges on a table can be quite time consuming during
3230 the open phase.  With most applications, the programmer already knows that the
3231 user has sufficient privileges to access the table, so this check is normally
3232 not required.
3233
3234 For best performance, open the table, and then use the
3235 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} function
3236 to check the users privileges.  Passing a schema to the TablePrivileges()
3237 function can significantly speed up the privileges checks.
3238
3239 \wxheading{See also}
3240
3241 \helpref{wxDb::TableExists}{wxdbtableexists},
3242 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
3243 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
3244
3245 \membersection{wxDbTable::OrderBy}\label{wxdbtableorderby}
3246
3247 \func{const wxString \&}{OrderBy}{}
3248
3249 \func{void}{OrderBy}{\param{const wxString \&}{OrderBy}}
3250
3251 Accessor function for the private class member wxDbTable::orderBy.  Can be
3252 used as a synonym for
3253 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
3254 (the first form of this function) or
3255 \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}
3256 (the second form of this function).
3257
3258 \wxheading{Parameters}
3259
3260 \docparam{OrderBy}{A comma separated list of column names that indicate the
3261 alphabetized/numeric sorting sequence that the result set is to be returned
3262 in.  If a FROM clause has also been specified, each column name specified in
3263 the ORDER BY clause should be prefaced with the table name to which the column
3264 belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
3265
3266 \wxheading{Return value}
3267
3268 The first form of this function returns the current value of the wxDbTable
3269 member variable ::orderBy.
3270
3271 The second form of the function has no return value.
3272
3273 \wxheading{See also}
3274
3275 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause},
3276 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
3277
3278 \membersection{wxDbTable::Query}\label{wxdbtablequery}
3279
3280 \func{virtual bool }{Query}{\param{bool }{forUpdate=false}, \param{bool }{distinct=false}}
3281
3282 \wxheading{Parameters}
3283
3284 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3285 as they are retrieved.  If the RDBMS is not capable of the FOR UPDATE clause,
3286 this argument is ignored.  See
3287 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3288 additional information regarding this argument.  Default is false.}
3289 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3290 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3291 applies to all columns returned in the result set, not individual columns.
3292 Default is false.}
3293
3294 \wxheading{Remarks}
3295
3296 This function queries records from the datasource based on the three
3297 wxDbTable members: "where", "orderBy", and "from".  Use
3298 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} to filter on
3299 records to be retrieved (e.g. All users with a first name of "JOHN").
3300 Use \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause} to
3301 change the sequence in which records are returned in the result set from
3302 the datasource (e.g. Ordered by LAST\_NAME).  Use
3303 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} to allow inner
3304 joining of the base table (the one being associated with this instance of
3305 wxDbTable) with other tables which share a related field.
3306
3307 After each of these clauses are set/cleared, call wxDbTable::Query() to
3308 fetch the result set from the datasource.
3309
3310 This scheme has an advantage if you have to requery your record set
3311 frequently in that you only have to set your WHERE, ORDER BY, and FROM
3312 clauses once.  Then to refresh the record set, simply call wxDbTable::Query()
3313 as frequently as needed.
3314
3315 Note that repeated calls to wxDbTable::Query() may tax the database
3316 server and make your application sluggish if done too frequently or
3317 unnecessarily.
3318
3319 The base table name is automatically prepended to the base column names in
3320 the event that the FROM clause has been set (is non-null) using
3321 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
3322
3323 The cursor for the result set is positioned {\it before} the first record in
3324 the result set after the query.  To retrieve the first record, call either
3325 \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} (only if backward scrolling
3326 cursors are available) or
3327 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.  Typically, no data from the
3328 result set is returned to the client driver until a request such as
3329 \helpref{wxDbTable::GetNext}{wxdbtablegetnext} is performed, so network
3330 traffic and database load are not overwhelmed transmitting data until the
3331 data is actually requested by the client.  This behavior is solely dependent
3332 on the ODBC driver though, so refer to the ODBC driver's reference material
3333 for information on its behaviors.
3334
3335 Values in the bound columns' memory variables are undefined after executing a
3336 call to this function and remain that way until a row in the result set is
3337 requested to be returned.
3338
3339 The wxDbTable::Query() function is defined as "virtual" so that it may be
3340 overridden for application specific purposes.
3341
3342 \normalbox{Be sure to set the wxDbTable's "where", "orderBy", and "from"
3343 member variables to "" if they are not to be used in the query.  Otherwise,
3344 the results returned may have unexpected results (or no results) due to
3345 improper or incorrect query parameters constructed from the uninitialized
3346 clauses.}
3347
3348 \wxheading{Example}
3349
3350 \begin{verbatim}
3351     // Incomplete code sample
3352     parts->SetWhereClause("DESCRIPTION = 'FOOD'");
3353     parts->SetOrderByClause("EXPIRATION_DATE");
3354     parts->SetFromClause("");
3355     // Query the records based on the where, orderBy and from clauses
3356     // specified above
3357     parts->Query();
3358     // Display all records queried
3359     while(parts->GetNext())
3360         dispPart(parts);  // user defined function
3361 \end{verbatim}
3362
3363 \membersection{wxDbTable::QueryBySqlStmt}\label{wxdbtablequerybysqlstmt}
3364
3365 \func{bool}{QueryBySqlStmt}{\param{const wxString \&}{pSqlStmt}}
3366
3367 Performs a query against the datasource by accepting and passing verbatim the
3368 SQL SELECT statement passed to the function.
3369
3370 \wxheading{Parameters}
3371
3372 \docparam{pSqlStmt}{Pointer to the SQL SELECT statement to be executed.}
3373
3374 \wxheading{Remarks}
3375
3376 This is the most powerful form of the query functions available.  This member
3377 function allows a programmer to write their own custom SQL SELECT statement
3378 for requesting data from the datasource.  This gives the programmer access
3379 to the full power of SQL for performing operations such as scalar functions,
3380 aggregate functions, table joins, and sub-queries, as well as datasource
3381 specific function calls.
3382
3383 The requirements of the SELECT statement are the following:
3384
3385 \begin{enumerate}
3386 \item Must return the correct number of columns.  In the derived
3387 wxDbTable constructor, it is specified how many columns are in
3388 the wxDbTable object. The SELECT statement must return exactly
3389 that many columns.
3390 \item The columns must be returned in the same sequence as specified
3391 when defining the bounds columns \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs},
3392 and the columns returned must be of the proper data type.  For
3393 example, if column 3 is defined in the wxDbTable bound column
3394 definitions to be a float, the SELECT statement must return a
3395 float for column 3 (e.g. PRICE * 1.10 to increase the price by
3396 10%).
3397 \item The ROWID can be included in your SELECT statement as the {\bf last}
3398 column selected, if the datasource supports it.  Use
3399 wxDbTable::CanUpdateByROWID() to determine if the ROWID can be
3400 selected from the datasource.  If it can, much better
3401 performance can be achieved on updates and deletes by including
3402 the ROWID in the SELECT statement.
3403 \end{enumerate}
3404
3405 Even though data can be selected from multiple tables (joins) in your select
3406 statement, only the base table associated with this wxDbTable object
3407 is automatically updated through the ODBC class library.  Data from multiple
3408 tables can be selected for display purposes however.  Include columns in
3409 the wxDbTable object and mark them as non-updateable (See
3410 \helpref{wxDbColDef}{wxdbcoldef} for details).  This way columns can be
3411 selected and displayed from other tables, but only the base table will be
3412 updated automatically when performed through the
3413 \helpref{wxDbTable::Update}{wxdbtableupdate} function after using this type of
3414 query.  To update tables other than the base table, use the
3415 \helpref{wxDbTable::Update}{wxdbtableupdate} function passing a SQL statement.
3416
3417 After this function has been called, the cursor is positioned before the
3418 first record in the record set.  To retrieve the first record, call
3419 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3420 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3421
3422 \wxheading{Example}
3423
3424 \begin{verbatim}
3425     // Incomplete code samples
3426          wxString sqlStmt;
3427     sqlStmt = "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
3428                AND CONTAINER = 12";
3429     // Query the records using the SQL SELECT statement above
3430     parts->QueryBySqlStmt(sqlStmt);
3431     // Display all records queried
3432     while(parts->GetNext())
3433         dispPart(&parts);
3434
3435     Example SQL statements
3436     ----------------------
3437
3438     // Table Join returning 3 columns
3439     SELECT PART_NUM, part_desc, sd_name
3440         from parts, storage_devices
3441         where parts.storage_device_id =
3442               storage_devices.storage_device_id
3443
3444     // Aggregate function returning total number of
3445     // parts in container 99
3446     SELECT count(*) from PARTS where container = 99
3447
3448     // Order by clause; ROWID, scalar function
3449     SELECT PART_NUM, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
3450         from parts
3451         where warehouse = 10
3452         order by PART_NUM desc           // descending order
3453
3454     // Subquery
3455     SELECT * from parts
3456         where container in (select container
3457         from storage_devices
3458             where device_id = 12)
3459 \end{verbatim}
3460
3461 \membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
3462
3463 \func{virtual bool }{QueryMatching}{\param{bool }{forUpdate=false},
3464 \param{bool }{distinct=false}}
3465
3466 QueryMatching allows querying of records from the table associated with
3467 the wxDbTable object by matching "columns" to values.
3468
3469 For example: To query the datasource for the row with a PART\_NUMBER column
3470 value of "32", clear all column variables of the wxDbTable object, set the
3471 PartNumber variable that is bound to the PART\_NUMBER column in the wxDbTable
3472 object to "32", and then call wxDbTable::QueryMatching().
3473
3474 \wxheading{Parameters}
3475
3476 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3477 as they are queried (SELECT ... FOR UPDATE).  If the RDBMS is not capable of
3478 the FOR UPDATE clause, this argument is ignored.  See
3479 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3480 additional information regarding this argument.  Default is false.}
3481 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3482 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3483 applies to all columns returned in the result set, not individual columns.
3484 Default is false.}
3485
3486 \wxheading{Remarks}
3487
3488 The SQL WHERE clause is built by the ODBC class library based on all
3489 non-zero/non-NULL columns in your wxDbTable object.  Matches can be on one,
3490 many or all of the wxDbTable's columns.  The base table name is prepended
3491 to the column names in the event that the wxDbTable's FROM clause is non-null.
3492
3493 This function cannot be used to perform queries which will check for
3494 columns that are 0 or NULL, as the automatically constructed WHERE clause
3495 only will contain comparisons on column member variables that are
3496 non-zero/non-NULL.
3497
3498 The primary difference between this function and \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields}
3499 is that this function can query on any column(s) in the wxDbTable object.
3500 Note however that this may not always be very efficient.  Searching on
3501 non-indexed columns will always require a full table scan.
3502
3503 The cursor is positioned before the first record in the record set after
3504 the query is performed.  To retrieve the first record, the program must call
3505 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3506 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3507
3508 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3509 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3510 this function.
3511
3512 \wxheading{Example}
3513
3514 \begin{verbatim}
3515     // Incomplete code sample
3516     parts->ClearMemberVars();           // Set all columns to zero
3517     wxStrcpy(parts->PartNumber,"32");   // Set columns to query on
3518     parts->OnHold = true;
3519     parts->QueryMatching();             // Query
3520     // Display all records queried
3521     while(parts->GetNext())
3522         dispPart(parts);  // Some application defined function
3523 \end{verbatim}
3524
3525 \membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
3526
3527 \func{bool }{QueryOnKeyFields}{\param{bool }{forUpdate=false},
3528 \param{bool }{distinct=false}}
3529
3530 QueryOnKeyFields provides an easy mechanism to query records in the table
3531 associated with the wxDbTable object by the primary index column(s).  Simply
3532 assign the primary index column(s) values and then call this member function
3533 to retrieve the record.
3534
3535 Note that since primary indexes are always unique, this function implicitly
3536 always returns a single record from the database. The base table name is
3537 prepended to the column names in the event that the wxDbTable's FROM clause
3538 is non-null.
3539
3540 \wxheading{Parameters}
3541
3542 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3543 as they are queried (SELECT ... FOR UPDATE).  If the RDBMS is not capable of
3544 the FOR UPDATE clause, this argument is ignored.  See
3545 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3546 additional information regarding this argument.  Default is false.}
3547 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3548 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3549 applies to all columns returned in the result set, not individual columns.
3550 Default is false.}
3551
3552 \wxheading{Remarks}
3553
3554 The cursor is positioned before the first record in the record set after
3555 the query is performed.  To retrieve the first record, the program must call
3556 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3557 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3558
3559 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3560 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3561 this function.
3562
3563 \wxheading{Example}
3564
3565 \begin{verbatim}
3566     // Incomplete code sample
3567     wxStrcpy(parts->PartNumber, "32");
3568     parts->QueryOnKeyFields();
3569     // Display all records queried
3570     while(parts->GetNext())
3571         dispPart(parts);  // Some application defined function
3572 \end{verbatim}
3573
3574 \membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
3575
3576 \func{bool}{Refresh}{\void}
3577
3578 This function re-reads the bound columns into the memory variables, setting
3579 them to the current values stored on the disk.
3580
3581 The cursor position and result set are unaffected by calls to this function.
3582 (The one exception is in the case where the record to be refreshed has been
3583 deleted by some other user or transaction since it was originally retrieved
3584 as part of the result set.  For most datasources, the default behavior in
3585 this situation is to return the value that was originally queried for the
3586 result set, even though it has been deleted from the database.  But this is
3587 datasource dependent, and should be tested before relying on this behavior.)
3588
3589 \wxheading{Remarks}
3590
3591 This routine is only guaranteed to work if the table has a unique primary
3592 index defined for it.  Otherwise, more than one record may be fetched and
3593 there is no guarantee that the correct record will be refreshed.  The
3594 table's columns are refreshed to reflect the current data in the database.
3595
3596 \membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
3597
3598 \func{bool}{SetColDefs}{\param{UWORD }{index}, \param{const wxString \&}{fieldName},
3599 \param{int }{dataType}, \param{void *}{pData}, \param{SWORD }{cType},
3600 \param{int }{size}, \param{bool }{keyField = false}, \param{bool }{updateable = true},
3601 \param{bool }{insertAllowed = true}, \param{bool }{derivedColumn = false}}
3602
3603 \func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{UWORD }{numCols}}
3604
3605 \wxheading{Parameters}
3606
3607 \docparam{index}{Column number (0 to n-1, where n is the number of columns
3608 specified as being defined for this wxDbTable instance when the
3609 wxDbTable constructor was called.}
3610 \docparam{fieldName}{Column name from the associated data table.}
3611 \docparam{dataType}{Logical data type.  Valid logical types include:}
3612
3613 \begin{verbatim}
3614     DB_DATA_TYPE_VARCHAR        : strings
3615     DB_DATA_TYPE_INTEGER        : non-floating point numbers
3616     DB_DATA_TYPE_FLOAT          : floating point numbers
3617     DB_DATA_TYPE_DATE           : dates
3618     DB_DATA_TYPE_BLOB           : binary large objects
3619     DB_DATA_TYPE_MEMO           : large strings
3620 \end{verbatim}
3621
3622 \docparam{pData}{Pointer to the data object that will hold the column's
3623 value when a row of data is returned from the datasource.}
3624 \docparam{cType}{SQL C Type.  This defines the data type that the SQL
3625 representation of the data is converted to to be stored in {\it pData}.
3626 Other valid types are available also, but these are the most common ones:}
3627
3628 \begin{verbatim}
3629     SQL_C_CHAR      // string - deprecated: use SQL_C_WXCHAR
3630     SQL_C_WXCHAR    // string - Used transparently in unicode or non-unicode builds
3631     SQL_C_LONG
3632     SQL_C_ULONG
3633     SQL_C_SHORT
3634     SQL_C_USHORT
3635     SQL_C_FLOAT
3636     SQL_C_DOUBLE
3637     SQL_C_NUMERIC
3638     SQL_C_TIMESTAMP
3639
3640     SQL_C_BOOLEAN   // defined in db.h
3641     SQL_C_ENUM      // defined in db.h
3642 \end{verbatim}
3643
3644 \docparam{size}{Maximum size in bytes of the {\it pData} object.}
3645 \docparam{keyField}{{\it OPTIONAL}.  Indicates if this column is part of the
3646 primary index.  Default is false.}
3647 \docparam{updateable}{{\it OPTIONAL}.  Are updates allowed on this column?
3648 Default is true.}
3649 \docparam{insertAllowed}{{\it OPTIONAL}.  Inserts allowed on this column?
3650 Default is true.}
3651 \docparam{derivedColumn}{{\it OPTIONAL}.  Is this a derived column (non-base
3652 table column for query only)?  Default is false.}
3653
3654 \docparam{colInfs}{Pointer to an array of wxDbColInf instances which contains
3655 all the information necessary to create {\it numCols} column definitions.}
3656 \docparam{numCols}{Number of elements of wxDbColInf type that are pointed
3657 to by {\it colInfs}, which are to have column definitions created from them.}
3658
3659 \wxheading{Remarks}
3660
3661 If {\it pData} is to hold a string of characters, be sure to include enough
3662 space for the NULL terminator in pData and in the byte count of {\it size}.
3663
3664 Using the first form of this function, if the column definition is not able
3665 to be created, a value of false is returned.  If the specified index of the
3666 column exceeds the number of columns defined in the wxDbTable instance, an
3667 assert is thrown and logged (in debug builds) and a false is returned.
3668
3669 A failure to create the column definition in the second form results in a
3670 value of NULL being returned.
3671
3672 Both forms of this function provide a shortcut for defining the columns in
3673 your wxDbTable object.  Use this function in any derived wxDbTable
3674 constructor when describing the column/columns in the wxDbTable object.
3675
3676 The second form of this function is primarily used when the
3677 \helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
3678 datasource for the column definitions, so that the column definitions are
3679 already stored in wxDbColInf form.  One example use of using
3680 \helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
3681 a data table existed in one datasource, and the table's column definitions
3682 were to be copied over to another datasource or table.
3683
3684 \wxheading{Example}
3685
3686 \begin{verbatim}
3687     // Long way not using this function
3688     wxStrcpy(colDefs[0].ColName, "PART_NUM");
3689     colDefs[0].DbDataType   = DB_DATA_TYPE_VARCHAR;
3690     colDefs[0].PtrDataObj   = PartNumber;
3691     colDefs[0].SqlCtype     = SQL_C_WXCHAR;
3692     colDefs[0].SzDataObj    = PART_NUMBER_LEN;
3693     colDefs[0].KeyField     = true;
3694     colDefs[0].Updateable   = false;
3695     colDefs[0].InsertAllowed= true;
3696     colDefs[0].DerivedCol   = false;
3697
3698     // Shortcut using this function
3699     SetColDefs(0, "PART_NUM", DB_DATA_TYPE_VARCHAR, PartNumber,
3700                SQL_C_WXCHAR, PART_NUMBER_LEN, true, false, true, false);
3701 \end{verbatim}
3702
3703 \membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
3704
3705 \func{void}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB\_DEFAULT\_CURSOR}}
3706
3707 \wxheading{Parameters}
3708
3709 \docparam{hstmtActivate}{{\it OPTIONAL}.  Pointer to the cursor that is to
3710 become the current cursor.  Passing no cursor handle will reset the cursor
3711 back to the wxDbTable's default (original) cursor that was created when the
3712 wxDbTable instance was first created.  Default is wxDB\_DEFAULT\_CURSOR.}
3713
3714 \wxheading{Remarks}
3715
3716 When swapping between cursors, the member variables of the wxDbTable object
3717 are automatically refreshed with the column values of the row that the
3718 current cursor is positioned at (if any).  If the cursor is not positioned,
3719 then the data in member variables is undefined.
3720
3721 The only way to return back to the cursor that was in use before this
3722 function was called is to programmatically determine the current cursor's HSTMT
3723 {\bf BEFORE} calling this function using \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor}
3724 and saving a pointer to that cursor.
3725
3726 \wxheading{See also}
3727
3728 \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor},
3729 \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor},
3730 \helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}
3731
3732 \membersection{wxDbTable::SetFromClause}\label{wxdbtablesetfromclause}
3733
3734 \func{void}{SetFromClause}{\param{const wxString \&}{From}}
3735
3736 Accessor function for setting the private class member wxDbTable::from
3737 that indicates what other tables should be inner joined with the wxDbTable's
3738 base table for access to the columns in those other tables.
3739
3740 Synonym to this function is one form of \helpref{wxDbTable::From}{wxdbtablefrom}
3741
3742 \wxheading{Parameters}
3743
3744 \docparam{From}{A comma separated list of table names that are to be inner
3745 joined with the base table's columns so that the joined table's columns
3746 may be returned in the result set or used as a portion of a comparison with
3747 the base table's columns.  NOTE that the base tables name must NOT be included
3748 in the FROM clause, as it is automatically included by the wxDbTable class
3749 in constructing query statements.}
3750
3751 \wxheading{Remarks}
3752
3753 Used by the \helpref{wxDbTable::Query}{wxdbtablequery} and
3754 \helpref{wxDbTable::Count}{wxdbtablecount} member functions to allow inner
3755 joining of records from multiple tables.
3756
3757 Do {\bf not} include the keyword "FROM" when setting the FROM clause.
3758
3759 If using the FROM clause when performing a query, be certain to include in
3760 the corresponding WHERE clause a comparison of a column from either the base
3761 table or one of the other joined tables to each other joined table to ensure
3762 the datasource knows on which column values the tables should be joined on.
3763
3764 \wxheading{Example}
3765
3766 \begin{verbatim}
3767     ...
3768     // Base table is the "LOCATION" table, and it is being
3769     // inner joined to the "PART" table via the field "PART_NUMBER"
3770     // that can be related between the two tables.
3771     location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
3772     location->SetFromClause("PART");
3773     ...
3774 \end{verbatim}
3775
3776 \wxheading{See also}
3777
3778 \helpref{wxDbTable::From}{wxdbtablefrom},
3779 \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
3780
3781 \membersection{wxDbTable::SetColNull}\label{wxdbtablesetcolnull}
3782
3783 \func{bool}{SetColNull}{\param{UWORD }{colNumber}, \param{bool }{set=true}}
3784
3785 \func{bool}{SetColNull}{\param{const wxString \&}{colName},
3786 \param{bool }{set=true}}
3787
3788 Both forms of this function allow a member variable representing a column
3789 in the table associated with this wxDbTable object to be set to NULL.
3790
3791 The first form allows the column to be set by the index into the column
3792 definitions used to create the wxDbTable instance, while the second allows
3793 the actual column name to be specified.
3794
3795 \wxheading{Parameters}
3796
3797 \docparam{colNumber}{Index into the column definitions used when first defining
3798 this wxDbTable object.}
3799 \docparam{colName}{Actual data table column name that is to be set to NULL.}
3800 \docparam{set}{Whether the column is set to NULL or not.  Passing true sets
3801 the column to NULL, passing false sets the column to be non-NULL.  Default is
3802 true.}
3803
3804 \wxheading{Remarks}
3805
3806 No database updates are done by this function.  It only operates on the
3807 member variables in memory.  Use and insert or update function to store this
3808 value to disk.
3809
3810 \membersection{wxDbTable::SetOrderByClause}\label{wxdbtablesetorderbyclause}
3811
3812 \func{void}{SetOrderByClause}{\param{const wxString \&}{OrderBy}}
3813
3814 Accessor function for setting the private class member wxDbTable::orderBy
3815 which determines sequence/ordering of the rows returned in the result set
3816 of a query.
3817
3818 A synonym to this function is one form of the function \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
3819
3820 \wxheading{Parameters}
3821
3822 \docparam{OrderBy}{A comma separated list of column names that indicate the
3823 alphabetized sorting sequence that the result set is to be returned in.  If
3824 a FROM clause has also been specified, each column name specified in the
3825 ORDER BY clause should be prefaced with the table name to which the column
3826 belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
3827
3828 \wxheading{Remarks}
3829
3830 Do {\bf not} include the keywords "ORDER BY" when setting the ORDER BY clause.
3831
3832 \wxheading{Example}
3833
3834 \begin{verbatim}
3835     ...
3836     parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
3837     ...
3838
3839     ...
3840     location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
3841     ...
3842 \end{verbatim}
3843
3844 \wxheading{See also}
3845
3846 \helpref{wxDbTable::OrderBy}{wxdbtableorderby},
3847 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
3848
3849 \membersection{wxDbTable::SetQueryTimeout}\label{wxdbtablesetquerytimeout}
3850
3851 \func{bool}{SetQueryTimeout}{\param{UDWORD }{nSeconds}}
3852
3853 Allows a time period to be set as the timeout period for queries.
3854
3855 \wxheading{Parameters}
3856
3857 \docparam{nSeconds}{The number of seconds to wait for the query to complete
3858 before timing out.}
3859
3860 \wxheading{Remarks}
3861
3862 Neither Oracle or Access support this function as of yet.  Other databases
3863 should be evaluated for support before depending on this function working
3864 correctly.
3865
3866 \membersection{wxDbTable::SetWhereClause}\label{wxdbtablesetwhereclause}
3867
3868 \func{void}{SetWhereClause}{\param{const wxString \&}{Where}}
3869
3870 Accessor function for setting the private class member wxDbTable::where
3871 that determines which rows are returned in the result set by the datasource.
3872
3873 A synonym to this function is one form of the function \helpref{wxDbTable::Where}{wxdbtablewhere}
3874
3875 \wxheading{Parameters}
3876
3877 \docparam{Where}{SQL "where" clause.  This clause can contain any SQL language
3878 that is legal in standard where clauses.  If a FROM clause has also been
3879 specified, each column name specified in the ORDER BY clause should be
3880 prefaced with the table name to which the column belongs using DOT notation
3881 (TABLE\_NAME.COLUMN\_NAME).}
3882
3883 \wxheading{Remarks}
3884
3885 Do {\bf not} include the keywords "WHERE" when setting the WHERE clause.
3886
3887 \wxheading{Example}
3888
3889 \begin{verbatim}
3890     ...
3891     // Simple where clause
3892     parts->SetWhereClause("PART_NUMBER = '32'");
3893     ...
3894     // Any comparison operators
3895     parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER%'");
3896     ...
3897     // Multiple comparisons, including a function call
3898     parts->Where("QTY > 0 AND {fn UCASE(PART_DESCRIP)} LIKE '%DRILL%'");
3899     ...
3900     // Using parameters and multiple logical combinations
3901     parts->Where("((QTY > 10) OR (ON_ORDER > 0)) AND ON_HOLD = 0");
3902     ...
3903     // This query uses an inner join (requiring a FROM clause also)
3904     // that joins the PART and LOCATION table on he common field
3905     // PART_NUMBER.
3906     parts->Where("PART.ON_HOLD = 0 AND \
3907                   PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
3908                   LOCATION.PART_NUMBER > 0");
3909 \end{verbatim}
3910
3911 \wxheading{See also}
3912
3913 \helpref{wxDbTable::Where}{wxdbtablewhere},
3914 \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
3915
3916 \membersection{wxDbTable::Update}\label{wxdbtableupdate}
3917
3918 \func{bool }{Update}{\void}
3919
3920 \func{bool }{Update}{\param{const wxString \&}{pSqlStmt}}
3921
3922 The first form of this function will update the row that the current cursor
3923 is currently positioned at with the values in the memory variables that
3924 are bound to the columns.  The actual SQL statement to perform the update
3925 is automatically created by the ODBC class, and then executed.
3926
3927 The second form of the function allows full access through SQL statements for
3928 updating records in the database.  Write any valid SQL UPDATE statement and
3929 submit it to this function for execution.  Sophisticated updates can be
3930 performed using the full power of the SQL dialect. The full SQL statement
3931 must have  the exact syntax required by the driver/datasource for performing
3932 the update.  This usually is in the form of:
3933
3934 \begin{verbatim}
3935     UPDATE tablename SET col1=X, col2=Y, ... where ...
3936 \end{verbatim}
3937
3938 \wxheading{Parameters}
3939
3940 \docparam{pSqlStmt}{Pointer to SQL UPDATE statement to be executed.}
3941
3942 \wxheading{Remarks}
3943
3944 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3945 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3946 this function to commit or rollback the update.
3947
3948 \wxheading{Example}
3949
3950 \begin{verbatim}
3951          wxString sqlStmt;
3952     sqlStmt = "update PART set QTY = 0 where PART_NUMBER = '32'";
3953 \end{verbatim}
3954
3955 \membersection{wxDbTable::UpdateWhere}\label{wxdbtableupdatewhere}
3956
3957 \func{bool}{UpdateWhere}{\param{const wxString \&}{pWhereClause}}
3958
3959 Performs updates to the base table of the wxDbTable object, updating only the
3960 rows which match the criteria specified in the {\it pWhereClause}.
3961
3962 All columns that are bound to member variables for this wxDbTable instance
3963 that were defined with the "updateable" parameter set to true will be updated
3964 with the information currently held in the memory variable.
3965
3966 \wxheading{Parameters}
3967
3968 \docparam{pWhereClause}{Pointer to a valid SQL WHERE clause.  Do not
3969 include the keyword 'WHERE'.}
3970
3971 \wxheading{Remarks}
3972
3973 Care should be used when updating columns that are part of indexes with
3974 this function so as not to violate an unique key constraints.
3975
3976 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3977 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3978 this function to commit or rollback the update(s).
3979
3980 \membersection{wxDbTable::Where}\label{wxdbtablewhere}
3981
3982 \func{const wxString \&}{Where}{}
3983
3984 \func{void}{Where}{\param{const wxString\& }{Where}}
3985
3986 Accessor function for the private class member wxDbTable::where.  Can be used
3987 as a synonym for \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
3988 (the first form of this function) to return the current where clause or
3989 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} (the second form
3990 of this function) to set the where clause for this table instance.
3991
3992 \wxheading{Parameters}
3993
3994 \docparam{Where}{A valid SQL WHERE clause.  Do not include the keyword 'WHERE'.}
3995
3996 \wxheading{Return value}
3997
3998 The first form of this function returns the current value of the wxDbTable
3999 member variable ::where.
4000
4001 The second form of the function has no return value, as it will always set
4002 the where clause successfully.
4003
4004 \wxheading{See also}
4005
4006 \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause},
4007 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
4008
4009 \membersection{wxDbTable::operator $++$}\label{wxdbtableplusplus}
4010
4011 \func{bool}{operator $++$}{\void}
4012
4013 Synonym for \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
4014
4015 \wxheading{See also}
4016
4017 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
4018
4019 \membersection{wxDbTable::operator $--$}\label{wxdbtableminusminus}
4020
4021 \func{bool}{operator $--$}{\void}
4022
4023 Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
4024
4025 \wxheading{See also}
4026
4027 \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
4028
4029 \section{\class{wxDbTableInf}}\label{wxdbtableinf}
4030
4031 \begin{verbatim}
4032     tableName[0]    = 0;
4033     tableType[0]    = 0;
4034     tableRemarks[0] = 0;
4035     numCols         = 0;
4036     pColInf         = NULL;
4037 \end{verbatim}
4038
4039 Currently only used by \helpref{wxDb::GetCatalog}{wxdbgetcatalog} internally
4040 and \helpref{wxDbInf}{wxdbinf} class, but may be used in future releases for
4041 user functions.  Contains information describing the table (Name, type, etc).
4042 A pointer to a wxDbColInf array instance is included so a program can create a
4043 \helpref{wxDbColInf}{wxdbcolinf} array instance (using
4044 \helpref{wxDb::GetColumns}{wxdbgetcolumns})
4045 to maintain all information about the columns of a table in one memory
4046 structure.
4047
4048 Eventually, accessor functions will be added for this class
4049
4050 See the \helpref{database classes overview}{odbcoverview} for
4051 an introduction to using the ODBC classes.
4052
4053 \wxheading{Include files}
4054
4055 <wx/db.h>
4056
4057 \wxheading{Library}
4058
4059 \helpref{wxOdbc}{librarieslist}
4060
4061 \latexignore{\rtfignore{\wxheading{Members}}}
4062
4063 \membersection{wxDbTableInf::Initialize}\label{wxdbtableinfinitialize}
4064
4065 Simply initializes all member variables to a cleared state.  Called by
4066 the constructor automatically.
4067
4068 \section{\class{wxDbGridColInfo}}\label{wxdbgridcolinfo}
4069
4070 This class is used  to define columns to be shown, names of the columns,
4071 order and type of data, when using \helpref{wxdbGridTableBase}{wxdbgridtablebase} to display
4072 a Table or query in a \helpref{wxGrid}{wxgrid}
4073
4074 See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} for
4075 an introduction to using the wxDbGrid classes.
4076
4077 \wxheading{Include files}
4078
4079 <wx/dbgrid.h>
4080
4081 \wxheading{Library}
4082
4083 \helpref{wxDbgrid}{librarieslist}
4084
4085 \latexignore{\rtfignore{\wxheading{Members}}}
4086
4087 \membersection{wxDbGridColInfo::wxDbGridColInfo}\label{wxdbgridcolinfoctor}
4088
4089 \func{}{wxDbGridColInfo}{\param{int }{colNumber}, \param{wxString }{type},
4090   \param{wxString }{title}, \param{wxDbGridColInfo *}{next}}
4091
4092 Default constructor. See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
4093 see two different ways for adding columns.
4094
4095
4096 \wxheading{Parameters}
4097
4098 \docparam{colNumber}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
4099 \docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
4100  use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
4101 \docparam{title}{The column label to be used in the grid display}
4102 \docparam{next}{A pointer to the next wxDbGridColInfo structure if using one-step
4103 construction, NULL  terminates the list. Use Null also if using two step construction.}
4104 See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
4105 see two different ways for adding columns.
4106
4107 \membersection{wxDbGridColInfo::\destruct{wxDbGridColInfo}}\label{wxdbgridcolinfodtor}
4108
4109 \func{}{\destruct{wxDbGridColInfo}}{}
4110
4111 Destructor.
4112
4113 \membersection{wxDbGridColInfo::AddColInfo}\label{wxdbgridcolinfoaddcolinfo}
4114
4115 \func{void}{AddColInfo}{\param{int }{colNumber},
4116 \param{wxString }{type}, \param{wxString }{title}}
4117
4118 Use this member function for adding columns. See the database
4119 grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
4120 see two different ways for adding columns.
4121
4122 It is important to note that this class is merely a specifier to the \helpref{wxDbGridTableBase}{wxdbgridtablebase}
4123 constructor. Changes made to this datatype after the \helpref{wxDbGridTableBase}{wxdbgridtablebase} is called will
4124 not have any effect.
4125
4126 \wxheading{Parameters}
4127 \docparam{colNumber}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
4128 \docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
4129  use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
4130 \docparam{title}{The column label to be used in the grid display}
4131
4132 \wxheading{Remarks}
4133
4134 As wxDbTable must be defined with to have columns which match those  to by a wxDbGridColInfo
4135 info structure as this is the structure which informs the grid of how you want to display your
4136 \helpref{wxDbTable}{wxdbtable}. If no datatype conversion or the referenced column number does not exist the
4137 the behavior is undefined.
4138
4139 See the example at \helpref{wxDbGridColInfo::wxDbGridColInfo}{wxdbgridcolinfoctor}.
4140
4141 \section{\class{wxDbGridTableBase}}\label{wxdbgridtablebase}
4142
4143 You can view a database table in a grid using this class.
4144
4145 If you are deriving your own wxDbTable subclass for your table , then you may consider
4146 overriding GetCol() and SetCol() to provide calculated fields. This does work but care should
4147 be taken when using wxDbGridTableBase in this way.
4148
4149 The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable
4150 object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable
4151 when an new on is assigned or wxGridTableBase's destructor is called.
4152 However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true);
4153 is  an error. If you need to requery an table object the preferred way is
4154 that the client keeps ownership.
4155
4156 \wxheading{Derived From}
4157
4158 \helpref{wxGridTableBase}{wxgridtablebase}
4159
4160 \wxheading{Include files}
4161
4162 <wx/dbgrid.h>
4163
4164 \wxheading{Library}
4165
4166 \helpref{wxDbgrid}{librarieslist}
4167
4168
4169 \wxheading{Example}
4170
4171 \begin{verbatim}
4172         // First step, let's define wxDbTable
4173         int numColumns = 2;
4174         wxDbTable *table = new wxDbTable (db, tblName, numColumns);
4175         int int_var;
4176         wxChar string_name[255];
4177         table->SetColDef (0, "column 0", DB_DATA_TYPE_INTEGER, &int_var,
4178                         SQL_C_LONG, sizeof(int_var), true);
4179         table->SetColDef (1, "column 1", DB_DATA_TYPE_VARCHAR, &string_name,
4180                         SQL_C_LONG, sizeof(string_name), false);
4181
4182     // now let's define columns in the grid
4183
4184     // first way to do it
4185     wxDbGridColInfo *columns;
4186     columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column",
4187               new wxDbGridColInfo(1, wxGRID_VALUE_STRING, "second column",
4188               NULL);
4189
4190     // second way to do it
4191     wxDbGridColInfo *columns;
4192     // first column is special
4193     columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column", NULL);
4194     // all the rest
4195     columns->AddColInfo (1, wxGRID_VALUE_STRING, "second column");
4196
4197     // second way may be better when columns are not known at compile time
4198
4199     // now, let's open the table and make a Query()
4200     table->Open();
4201     // this step is very important
4202     table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
4203     // in the grid we will see only the rows of the result query
4204     m_dbTable->Query();
4205
4206     wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, true);
4207     delete columns;  // not needed anymore
4208     wxGrid *grid = new wxGrid ( ... );
4209     grid->SetTable(dbgrid, true);
4210     grid->Fit();
4211 \end{verbatim}
4212
4213
4214 \wxheading{Include files}
4215
4216 <wx/dbgrid.h>
4217
4218 \wxheading{Helper classes and data structures}
4219
4220 \membersection{wxDbGridTableBase::wxDbGridTableBase}\label{wxdbgridtablebaseconstr}
4221
4222 \func{}{wxDbGridTableBase}{\param{wxDbTable *}{tab}, \param{wxDbGridColInfo *}{ColInfo},
4223   \param{int }{count = wxUSE\_QUERY}, \param{bool }{takeOwnership = true}}
4224
4225 Constructor.
4226
4227 \wxheading{Parameters}
4228
4229 \docparam{tab}{ The database table you want to display. Must be opened and queried before display the grid.
4230 See the example \helpref{above}{wxdbgridtablebase}.}
4231 \docparam{ColInfo}{ Columns titles, and other values. See \helpref{wxDbGridColInfo}{wxdbgridcolinfo}.}
4232 \docparam{count}{You can use a query result set (wxUSE\_QUERY, to use wxDbTable::Count(wxDbTable::Count()
4233  or you can fix the total number of rows (count >= 0) to display, or specify it if you already know the size in avoid calling }
4234
4235 \docparam{takeOwnership}{ If true, this class deletes wxDbTable when it stops
4236 referring to it, if false application must
4237 take care of deleting it.  }
4238
4239 \membersection{wxDbGridTableBase::ValidateRow}\label{wxdbgridtablebasevalidate}
4240
4241 \func{void}{ValidateRow}{\param{int }{row}}
4242
4243 It ensures that the row data is fetched from the database, and it the wxDbTable local buffer,
4244 the row number passed should be the grid row.
4245
4246 \wxheading{Parameters}
4247
4248 \docparam{row}{ Row where validation must be done. }
4249
4250 \membersection{wxDbGridTableBase::UpdateRow}\label{wxdbgridtablebaseupdaterow}
4251
4252 \func{bool}{UpdateRow}{\param{int }{row}}
4253
4254 If row has changed it forces that row to be written back to the database, however support
4255 for detecting whether insert/update is required is currently not in wxDbTable, so this
4256 function is currently unsupported.
4257
4258 \wxheading{Parameters}
4259
4260 \docparam{row}{ Row you want to update. }
4261
4262 \membersection{wxDbGridTableBase::AssignDbTable}\label{wxdbgridtablebaseassigndbtable}
4263
4264 \func{bool}{AssignDbTable}{\param{wxDbTable *}{tab},\param{int }{count = wxUSE\_QUERY},
4265 \param{bool }{takeOwnership = true}}
4266
4267 Resets the grid for using with a new database table, but using the same columns definition.
4268 This can be useful when re-querying the database and want to see the changes.
4269
4270 \wxheading{Parameters}
4271
4272 \docparam{tab}{ Database table you want to assign to the grid. }
4273 \docparam{count}{ Number of rows you want to show or wxUSE\_QUERY for using a query. }
4274 \docparam{takeOwnership}{ If false, user must take care of deleting tab after deleting
4275 the wxDbGridTableBase. If true, deletion is made by destructor class. }
4276