docs/latex/wx/db.tex

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