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