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 wxWidgets 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.
 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 wxWidgets 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 wxWidgets) 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 wxWidgets v2.4 release, this function is a renamed version of
1097 wxDb::FwdOnlyCursors() to match the normal wxWidgets 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 wxWidgets
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}, \param{bool }{failOnDataTypeUnsupported}}
1189
1190 \func{bool}{Open}{\param{const wxString \&}{inConnectStr},
1191 \param{bool }{failOnDataTypeUnsupported}}
1192
1193 \func{bool}{Open}{\param{wxDbConnectInf *}{dbConnectInf},
1194 \param{bool }{failOnDataTypeUnsupported}}
1195
1196 \func{bool}{Open}{\param{wxDb *}{copyDb}}
1197
1198 Opens a connection to the datasource, sets certain behaviors of the datasource
1199 to confirm to the accepted behaviors (e.g. cursor position maintained on
1200 commits), and queries the datasource for its representations of the basic
1201 datatypes to determine the form in which the data going to/from columns in
1202 the data tables are to be handled.
1203
1204 The second form of this function, which accepts a "wxDb *" as a parameter,
1205 can be used to avoid the overhead (execution time, database load, network
1206 traffic) which are needed to determine the data types and representations
1207 of data that are necessary for cross-datasource support by these classes.
1208
1209 Normally the first form of the wxDb::Open() function will open the connection
1210 and then send a series of queries to the datasource asking it for its
1211 representation of data types, and all the features it supports.  If one
1212 connection to the datasource has already been made previously, the information
1213 gathered when that connection was created can just be copied to any new
1214 connections to the same datasource by passing a pointer to the first
1215 connection in as a parameter to the wxDb::Open() function.  Note that this
1216 new connection created from the first connections information will use the
1217 same Dsn/Uid/AuthStr as the first connection used.
1218
1219 \wxheading{Parameters}
1220
1221 \docparam{Dsn}{datasource name.  The name of the ODBC datasource as
1222 assigned when the datasource is initially set up through the ODBC data
1223 source manager.}
1224 \docparam{Uid}{User ID.  The name (ID) of the user you wish to connect as
1225 to the datasource.  The user name (ID) determines what objects you
1226 have access to in the datasource and what datasource privileges you have.
1227 Privileges include being able to create new objects, update objects, delete
1228 objects and so on.  Users and privileges are normally administered by the
1229 database administrator.}
1230 \docparam{AuthStr}{The password associated with the Uid.}
1231 \docparam{failOnDataTypeUnsupporte}{As part of connecting to a database, the
1232 wxDb::Open() function will query the database to find out the native types
1233 that it supports.  With some databases, some data types may not be supported,
1234 or not sufficiently supported, for use with the wxODBC classes.  Normally
1235 a program should fail in this case, so as not to try to use a data type
1236 that is not supported.  This parameter allows the programmer to override the
1237 failure if they wish and continue on using the connection.}
1238 \docparam{dbConnectInf}{Contains a DSN, Uid, Password, or a connection string
1239 to be used in opening a new connection to the database.  If a connection
1240 string is present, then the connection string will be used.  If there is no
1241 connection string present, then the DSN, Uid, and Password are used.}
1242 \docparam{inConnectStr}{A valid ODBC connection string used to connect to a
1243 database}
1244 \docparam{copyDb}{Already completely configured and opened datasource
1245 connection from which all Dsn, Uid, AuthStr, connection string, and data
1246 typing information is to be copied from for use by this datasource
1247 connection.  If 'copyDb' used a connection string to create its connection
1248 originally, then the connection being made by this call to wxDb::Open() will
1249 use that same connection string.}
1250
1251 \wxheading{Remarks}
1252
1253 After a wxDb instance is created, it must then be opened.  When opening a
1254 datasource, there must be three pieces of information passed.  The data
1255 source name, user name (ID) and the password for the user.  No database
1256 activity on the datasource can be performed until the connection is opened.
1257 This is normally done at program startup and the datasource remains
1258 open for the duration of the program/module run.
1259
1260 It is possible to have connections to multiple datasources open at the same
1261 time to support distributed database connections by having separate instances
1262 of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.
1263
1264 If this function returns a value of false, it does not necessarily mean that
1265 the connection to the datasource was not opened.  It may mean that some
1266 portion of the initialization of the connection failed (such as a datatype not
1267 being able to be determined how the datasource represents it).  To determine
1268 if the connection to the database failed, use the \helpref{wxDb::IsOpen}{wxdbisopen}
1269 function after receiving a false result back from this function to determine if
1270 the connection was opened or not.  If this function returns false, but \helpref{wxDb::IsOpen}{wxdbisopen}
1271 returns true, then direct SQL commands may be passed to the database
1272 connection and can be successfully executed, but use of the datatypes (such as
1273 by a wxDbTable instance) that are normally determined during open will not be
1274 possible.
1275
1276 \normalbox{The {\it Dsn}, {\it Uid}, and {\it AuthStr} string pointers that are passed in
1277 are copied.  NOT the strings themselves, only the pointers.  The calling routine
1278 must maintain the memory for these three strings for the life of the wxDb instance.}
1279
1280 \wxheading{Example}
1281
1282 \begin{verbatim}
1283    wxDb sampleDB(DbConnectInf.GetHenv());
1284    if (!sampleDB.Open("Oracle 7.1 HP/UX", "gtasker", "myPassword"))
1285    {
1286       if (sampleDb.IsOpen())
1287       {
1288         // Connection is open, but the initialization of
1289         // datatypes and parameter settings failed
1290       }
1291       else
1292       {
1293         // Error opening datasource
1294       }
1295    }
1296 \end{verbatim}
1297
1298 \membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}
1299
1300 \func{bool}{RollbackTrans}{\void}
1301
1302 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.
1303
1304 \wxheading{Remarks}
1305
1306 Transactions begin implicitly as soon as you make a change to the database.  The
1307 transaction continues until either a commit or rollback is executed.  Calling
1308 wxDb::RollbackTrans() will result in ALL changes done using this database
1309 connection that have not already been committed to be "undone" back to the last
1310 commit/rollback that was successfully executed.
1311
1312 \normalbox{Calling this member function rolls back ALL open (uncommitted)
1313 transactions on this ODBC connection, including all wxDbTable instances that
1314 use this connection.}
1315
1316 \wxheading{See also}
1317
1318 \helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors
1319
1320 \membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
1321
1322 \func{void}{SetDebugErrorMessages}{\param{bool }{state}}
1323
1324 \docparam{state}{Either true (debug messages are logged) or false (debug
1325 messages are not logged).}
1326
1327 \wxheading{Remarks}
1328
1329 Turns on/off debug error messages from the ODBC class library.  When
1330 this function is passed true, errors are reported to the user/logged automatically
1331 in a text or pop-up dialog when an ODBC error occurs.  When passed false,
1332 errors are silently handled.
1333
1334 When compiled in release mode (FINAL=1), this setting has no affect.
1335
1336 \wxheading{See also}
1337
1338 \helpref{wxDb constructor}{wxdbconstr}
1339
1340 \membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
1341
1342 \func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxString \&}{filename = SQL\_LOG\_FILENAME}, \param{bool }{ append = false}}
1343
1344 \wxheading{Parameters}
1345
1346 \docparam{state}{Either sqlLogOFF or sqlLogON (see \helpref{enum wxDbSqlLogState}{wxdbcolfor}). Turns logging of SQL commands sent to the datasource OFF or ON.}
1347 \docparam{filename}{{\it OPTIONAL}.  Name of the file to which the log text is to be written.  Default is SQL\_LOG\_FILENAME.}
1348 \docparam{append}{{\it OPTIONAL}. Whether the file is appended to or overwritten.  Default is false.}
1349
1350 \wxheading{Remarks}
1351
1352 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.
1353
1354 When called with {\it sqlLogOFF}, the logging file is closed, and any calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} are ignored.
1355
1356 \membersection{wxDb::SQLColumnName}\label{wxdbsqlcolumnname}
1357
1358 \func{const wxString}{SQLColumnName}{\param{const char *}{ colName}}
1359
1360 Returns the column name in a form ready for use in SQL statements.
1361 In most cases, the column name is returned verbatim.  But some databases
1362 (e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which
1363 must be specially quoted.  For example, if the datasource allows spaces
1364 in the column 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 DBMS that is currently connected to with this connection.
1367
1368 \wxheading{Parameters}
1369
1370 \docparam{colName}{Native name of the column in the table that is to be
1371 evaluated to determine if any special quoting marks needed to be added to it
1372 before including the column name in a SQL statement}
1373
1374 \wxheading{See also}
1375
1376 \helpref{wxDb::SQLTableName}{wxdbsqltablename}
1377
1378 \membersection{wxDb::SQLTableName}\label{wxdbsqltablename}
1379
1380 \func{const wxString}{SQLTableName}{\param{const char *}{ tableName}}
1381
1382 Returns the table name in a form ready for use in SQL statements.
1383 In most cases, the table name is returned verbatim.  But some databases
1384 (e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which
1385 must be specially quoted.  For example, if the datasource allows spaces
1386 in the table name, the returned string will have the correct enclosing
1387 marks around the name to allow it to be properly included in a SQL statement
1388 for the data source that is currently connected to with this connection.
1389
1390 \wxheading{Parameters}
1391
1392 \docparam{tableName}{Native name of the table that is to be evaluated to
1393 determine if any special quoting marks needed to be added to it
1394 before including the table name in a SQL statement}
1395
1396 \wxheading{See also}
1397
1398 \helpref{wxDb::SQLColumnName}{wxdbsqlcolumnname}
1399
1400 \membersection{wxDb::TableExists}\label{wxdbtableexists}
1401
1402 \func{bool}{TableExists}{\param{const wxString \&}{tableName}, \param{const wxChar *}{userID=NULL}, \param{const wxString \&}{path=""}}
1403
1404 Checks the ODBC datasource for the existence of a table.  If a {\it userID}
1405 is specified, then the table must be accessible by that user (user must have
1406 at least minimal privileges to the table).
1407
1408 \wxheading{Parameters}
1409
1410 \docparam{tableName}{Name of the table to check for the existence of.}
1411 \docparam{userID}{Owner of the table (also referred to as schema).  Specify a userID when the datasource you are connected
1412 to allows multiple unique tables with the same name to be owned by different users.  {\it userID}
1413 is evaluated as follows:}
1414
1415 \begin{verbatim}
1416          userID == NULL  ... UserID is ignored (DEFAULT)
1417          userID == ""    ... UserID set equal to 'this->uid'
1418          userID != ""    ... UserID set equal to 'userID'
1419 \end{verbatim}
1420
1421 \wxheading{Remarks}
1422
1423 {\it tableName} may refer to a table, view, alias or synonym.
1424
1425 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.
1426
1427 \wxheading{See also}
1428
1429 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
1430
1431 \membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}
1432
1433 \func{bool}{TablePrivileges}{\param{const wxString \&}{tableName}, \param{const wxString \&}{priv},
1434 \param{const wxChar *}{userID=NULL}, \param{const wxChar *}{schema=NULL},
1435 \param{const wxString \&}{path=""}}
1436
1437 Checks the ODBC datasource for the existence of a table.  If a {\it userID}
1438 is specified, then the table must be accessible by that user (user must have
1439 at least minimal privileges to the table).
1440
1441 \wxheading{Parameters}
1442
1443 \docparam{tableName}{Name of the table on which to check privileges.
1444 {\it tableName} may refer to a table, view, alias or synonym.}
1445 \docparam{priv}{The table privilege being evaluated. May be one of the
1446 following (or a datasource specific privilege):}
1447
1448 \begin{verbatim}
1449     SELECT      : The connected user is permitted to retrieve data for
1450                   one or more columns of the table.
1451
1452     INSERT      : The connected user is permitted to insert new rows
1453                   containing data for one or more columns into the
1454                   table.
1455
1456     UPDATE      : The connected user is permitted to update the data in
1457                   one or more columns of the table.
1458
1459     DELETE      : The connected user is permitted to delete rows of
1460                   data from the table.
1461
1462     REFERENCES  : Is the connected user permitted to refer to one or
1463                   more columns of the table within a constraint (for
1464                   example, a unique, referential, or table check
1465                   constraint).
1466 \end{verbatim}
1467
1468 \docparam{userID}{{\it OPTIONAL.}  User for which to determine if the privilege
1469 specified to be checked is granted or not.  Default is "".
1470 {\it userID} is evaluated as follows:}
1471
1472 \begin{verbatim}
1473          userID == NULL  ... NOT ALLOWED!
1474          userID == ""    ... UserID set equal to 'this->uid'
1475          userID != ""    ... UserID set equal to 'userID'
1476 \end{verbatim}
1477
1478 \docparam{schema}{{\it OPTIONAL.}  Owner of the table.  Specify a userID when the datasource
1479 you are connected to allows multiple unique tables with the same name to be
1480 owned by different users.  Specifying the table owner makes determination of the
1481 users privileges MUCH faster.  Default is NULL.  {\it userID} is
1482 evaluated as follows:}
1483
1484 \begin{verbatim}
1485          schema == NULL  ... Any owner (DEFAULT)
1486          schema == ""    ... Owned by 'this->uid'
1487          schema != ""    ... Owned by userID specified in 'schema'
1488 \end{verbatim}
1489
1490 \docparam{path}{{\it OPTIONAL.}  Path to the table.  Default is "".
1491 Currently unused.}
1492
1493 \wxheading{Remarks}
1494
1495 The scope of privilege allowed to the connected user by a given table
1496 privilege is datasource dependent.
1497
1498 For example, the privilege UPDATE might allow the connected user to update
1499 all columns in a table on one datasource, but only those columns for
1500 which the grantor (the user that granted the connected user) has the UPDATE
1501 privilege on another datasource.
1502
1503 Looking up a user's privileges to a table can be time consuming depending on the
1504 datasource and ODBC driver.  This time can be minimized by passing a {\it schema}
1505 as a parameter.  With some datasources/drivers, the difference can be several
1506 seconds of time difference.
1507
1508
1509 \membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}
1510
1511 \func{int }{TranslateSqlState}{\param{const wxString \&}{SQLState}}
1512
1513 Converts an ODBC sqlstate to an internal error code.
1514
1515 \wxheading{Parameters}
1516
1517 \docparam{SQLState}{State to be converted.}
1518
1519 \wxheading{Return value}
1520
1521 Returns the internal class DB\_ERR code.  See \helpref{wxDb::DB\_STATUS}{wxdb} definition.
1522
1523 \membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
1524
1525 \func{bool}{WriteSqlLog}{\param{const wxString \&}{logMsg}}
1526
1527 \wxheading{Parameters}
1528
1529 \docparam{logMsg}{Free form string to be written to the log file.}
1530
1531 \wxheading{Remarks}
1532
1533 Very useful debugging tool that may be turned on/off during run time (see
1534 (see \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging} for details on
1535 turning logging on/off).  The passed in string {\it logMsg} will be written to
1536 a log file if SQL logging is turned on.
1537
1538 \wxheading{Return value}
1539
1540 If SQL logging is off when a call to WriteSqlLog() is made, or there is a
1541 failure to write the log message to the log file, the function returns
1542 false without performing the requested log, otherwise true is returned.
1543
1544 \wxheading{See also}
1545
1546 \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
1547
1548 \section{\class{wxDbColDataPtr}}\label{wxdbcoldataptr}
1549
1550 Pointer to dynamic column definitions for use with a wxDbTable instance.
1551 Currently there are no member functions for this class.
1552
1553 See the \helpref{database classes overview}{odbcoverview} for
1554 an introduction to using the ODBC classes.
1555
1556 \begin{verbatim}
1557     void   *PtrDataObj;
1558     int     SzDataObj;
1559     SWORD   SqlCtype;
1560 \end{verbatim}
1561
1562 \section{\class{wxDbColDef}}\label{wxdbcoldef}
1563
1564 This class is used to hold information about the columns bound to an
1565 instance of a wxDbTable object.
1566
1567 Each instance of this class describes one column in the wxDbTable
1568 object.  When calling the \helpref{wxDb constructor}{wxdbconstr}, a
1569 parameter passed in indicates the number of columns that will be defined for
1570 the wxDbTable object.  The constructor uses this information to allocate
1571 adequate memory for all of the column descriptions in your wxDbTable object.
1572 Private member wxDbTable::colDefs is a pointer to this chunk of memory
1573 maintained by the wxDbTable class (and can be retrieved using the
1574 \helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs} function).
1575 To access the nth column definition of your wxDbTable object, just reference
1576 wxDbColDefs element [n - 1].
1577
1578 Typically, \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} is used to
1579 populate an array of these data structures for the wxDbTable instance.
1580
1581 Currently there are no accessor functions for this class, so all members are
1582 public.
1583
1584 \begin{verbatim}
1585     wxChar  ColName[DB_MAX_COLUMN_NAME_LEN+1];  // Column Name
1586     int     DbDataType;    - Logical Data Type;
1587                              e.g. DB_DATA_TYPE_INTEGER
1588     SWORD   SqlCtype;      - C data type; e.g. SQL_C_LONG
1589     void   *PtrDataObj;    - Address of the data object
1590     int     SzDataObj;     - Size, in bytes, of the data object
1591     bool    KeyField;      - Is column part of the PRIMARY KEY for the
1592                              table? -- Date fields should NOT be
1593                              KeyFields
1594     bool    Updateable;    - Column is updateable?
1595     bool    InsertAllowed; - Column included in INSERT statements?
1596     bool    DerivedCol;    - Column is a derived value?
1597     SDWORD  CbValue;       - !!!Internal use only!!!
1598     bool    Null;          - NOT FULLY IMPLEMENTED
1599                              Allows NULL values in Inserts and Updates
1600 \end{verbatim}
1601
1602 \wxheading{See also}
1603
1604 \helpref{database classes overview}{odbcoverview},
1605 \helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs}, \helpref{wxDb constructor}{wxdbconstr}
1606
1607 \membersection{wxDbColDef::Initialize}\label{wxdbcoldefinitialize}
1608
1609 Simply initializes all member variables to a cleared state.  Called by
1610 the constructor automatically.
1611
1612 \section{\class{wxDbColFor}}\label{wxdbcolfor}
1613
1614 Beginning support for handling international formatting specifically on dates
1615 and floats.
1616
1617 \begin{verbatim}
1618     wxString       s_Field;       // Formated String for Output
1619     wxString       s_Format[7];   // Formated Objects - TIMESTAMP has
1620                                      the biggest (7)
1621     wxString       s_Amount[7];   // Formated Objects - amount of
1622                                      things that can be formatted
1623     int            i_Amount[7];   // Formated Objects -
1624                                         TT MM YYYY HH MM SS m
1625     int            i_Nation;      // 0 = timestamp
1626                                      1 = EU
1627                                      2 = UK
1628                                      3 = International
1629                                      4 = US
1630     int            i_dbDataType;  // conversion of the 'sqlDataType'
1631                                      to the generic data type used by
1632                                      these classes
1633     SWORD          i_sqlDataType;
1634 \end{verbatim}
1635
1636 The constructor for this class initializes all the values to zero or NULL.
1637
1638 The destructor does nothing at this time.
1639
1640 Only one function is provided with this class currently.
1641
1642 See the \helpref{database classes overview}{odbcoverview} for
1643 an introduction to using the ODBC classes.
1644
1645 \membersection{wxDbColFor::Format}\label{wxdbcolforformat}
1646
1647 \func{int }{Format}{\param{int }{Nation}, \param{int }{dbDataType},
1648 \param{SWORD }{sqlDataType}, \param{short }{columnSize},
1649 \param{short }{decimalDigits}}\label{wxdbcolforformat}
1650
1651 Work in progress, and should be inter-related with wxLocale eventually.
1652
1653 \membersection{wxDbColFor::Initialize}\label{wxdbcolforinitialize}
1654
1655 Simply initializes all member variables to a cleared state.  Called by
1656 the constructor automatically.
1657
1658 \section{\class{wxDbColInf}}\label{wxdbcolinf}
1659
1660 Used with the \helpref{wxDb::GetColumns}{wxdbgetcolumns} functions for obtaining all retrievable information about a column's definition.
1661
1662 \begin{verbatim}
1663     wxChar       catalog[128+1];
1664     wxChar       schema[128+1];
1665     wxChar       tableName[DB_MAX_TABLE_NAME_LEN+1];
1666     wxChar       colName[DB_MAX_COLUMN_NAME_LEN+1];
1667     SWORD        sqlDataType;
1668     wxChar       typeName[128+1];
1669     SWORD        columnSize;
1670     SWORD        bufferLength;
1671     short        decimalDigits;
1672     short        numPrecRadix;
1673     short        nullable;
1674     wxChar       remarks[254+1];
1675     int          dbDataType;  // conversion of the 'sqlDataType'
1676                               // to the generic data type used by
1677                               // these classes
1678     int          PkCol;       // Primary key column
1679                                     0 = No
1680                                     1 = First Key
1681                                     2 = Second Key, etc...
1682     wxChar       PkTableName[DB_MAX_TABLE_NAME_LEN+1];
1683                               // Tables that use this PKey as a FKey
1684     int          FkCol;       // Foreign key column
1685                                     0 = No
1686                                     1 = First Key
1687                                     2 = Second Key, etc...
1688     wxChar       FkTableName[DB_MAX_TABLE_NAME_LEN+1];
1689                               // Foreign key table name
1690     wxDbColFor  *pColFor;     // How should this column be formatted
1691 \end{verbatim}
1692
1693 The constructor for this class initializes all the values to zero, "", or NULL.
1694
1695 The destructor for this class takes care of deleting the pColFor member if
1696 it is non-NULL.
1697
1698 See the \helpref{database classes overview}{odbcoverview} for
1699 an introduction to using the ODBC classes.
1700
1701 \membersection{wxDbColInf::Initialize}\label{wxdbcolinfinitialize}
1702
1703 Simply initializes all member variables to a cleared state.  Called by
1704 the constructor automatically.
1705
1706 \section{\class{wxDbConnectInf}}\label{wxdbconnectinf}
1707
1708 This class is used for holding the data necessary for connecting to the ODBC
1709 datasource.  That information includes: SQL environment handle, datasource
1710 name, user ID, password and default directory path (used with dBase).  Other
1711 optional fields held in this class are and file type, both for future
1712 functions planned to be added for creating/manipulating datasource definitions.
1713
1714 \membersection{wxDbConnectInf::wxDbConnectInf}
1715
1716 \func{}{wxDbConnectInf}{\void}
1717
1718 Default constructor.
1719
1720 \func{}{wxDbConnectInf}{\param{HENV }{henv}, \param{const wxString \&}{dsn},
1721 \param{const wxString \&}{userID=""}, \param{const wxString \&}{password},
1722 \param{const wxString \&}{defaultDir=""}, \param{const wxString \&}{description=""},
1723 \param{const wxString \&}{fileType=""}}
1724
1725 Constructor which allows initial settings of all the classes member variables.
1726
1727 See the special note below on the henv parameter for forcing this constructor
1728 to create a SQL environment handle automatically, rather than needing to pass
1729 one in to the function.
1730
1731 \wxheading{Parameters}
1732
1733 \docparam{henv}{Environment handle used for this connection.  See\rtfsp
1734 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv} for how to create
1735 an SQL environment handle.  NOTE: Passing in a NULL for this parameter will
1736 inform the constructor that it should create its own SQL environment handle.
1737 If NULL is passed for this parameter, the constructor will call\rtfsp
1738 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv} internally.  A
1739 flag is set internally also to indicate that the HENV was created by the
1740 constructor so that when the default class destructor is called, the
1741 destructor will call \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}\rtfsp
1742 to free the environment handle automatically.}
1743 \docparam{dsn}{Name of the datasource to be used in creating wxDb instances
1744 for creating connection(s) to a datasource.}
1745 \docparam{userID}{{\it OPTIONAL} Many datasources allow (or even require)
1746 use of a username to determine privileges that connecting user is allowed
1747 to have when accessing the datasource or the data tables.  Default is "".}
1748 \docparam{password}{{\it OPTIONAL} Password to be associated with the user
1749 ID specified in 'userID'.  Default is "".}
1750 \docparam{defaultDir}{{\it OPTIONAL} Used for datasources which require the
1751 path to where the data file is stored to be specified.  dBase is one example
1752 of the type of datasource which requires this information.  Default is "".}
1753 \docparam{description}{{\it OPTIONAL} {\bf FUTURE USE} Default is "".}
1754 \docparam{fileType}{{\it OPTIONAL} {\bf FUTURE USE} Default is "".}
1755
1756 \wxheading{Remarks}
1757
1758 It is strongly recommended that programs use the longer form of the
1759 constructor and allow the constructor to create the SQL environment handle
1760 automatically, and manage the destruction of the handle.
1761
1762 \wxheading{Example}
1763
1764 \begin{verbatim}
1765    wxDbConnectInf *DbConnectInf;
1766
1767         DbConnectInf = new wxDbConnectInf(0,"MY_DSN", "MY_USER", "MY_PASSWORD");
1768
1769         ....the rest of the program
1770
1771         delete DbConnectInf;
1772 \end{verbatim}
1773
1774 \wxheading{See also}
1775
1776 \helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv},
1777 \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}
1778
1779 \membersection{wxDbConnectInf::\destruct{wxDbConnectInf}}\label{wxdbconnectinfdestr}
1780
1781 \func{}{\destruct{wxDbConnectInf}}{}
1782
1783 Handles the default destruction of the instance of the class.  If the long form
1784 of the \helpref{wxDConnectInf}{wxdbconnectinf} was used, then this destructor
1785 also takes care of calling\rtfsp
1786 \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv} to free the
1787 SQL environment handle.
1788
1789 \membersection{wxDbConnectInf::AllocHenv}\label{wxdbconnectinfallochenv}
1790
1791 \func{bool }{AllocHenv}{\void}
1792
1793 Allocates a SQL environment handle that will be used to interface with
1794 an ODBC datasource.
1795
1796 \wxheading{Remarks}
1797
1798 This function can be automatically called by the long from of the
1799 \helpref{wxDbConnectInf}{wxdbconnectinf} constructor.
1800
1801 \membersection{wxDbConnectInf::FreeHenv}\label{wxdbconnectinffreehenv}
1802
1803 \func{void}{FreeHenv}{\void}
1804
1805 Frees the SQL environment handle being managed by the instance of this class.
1806
1807 \wxheading{Remarks}
1808
1809 If the SQL environment handle was created using the long form of the\rtfsp
1810 \helpref{wxDbConnectInf}{wxdbconnectinf} constructor, then the flag indicating
1811 that the HENV should be destroyed when the classes destructor is called
1812 is reset to be false, so that any future handles created using the\rtfsp
1813 \helpref{wxDbConnectInf::AllocHenv}{wxdbconnectinfallochenv} function
1814 must be manually released with a call to this function.
1815
1816 \membersection{wxDbConnectInf::Initialize}\label{wxdbconnectinfinitialize}
1817
1818 Simply initializes all member variables to a cleared state.  Called by
1819 the constructor automatically.
1820
1821 \membersection{wxDbConnectInf::GetAuthStr}\label{wxdbconnectinfgetauthstr}
1822
1823 \func{const wxChar *}{GetAuthStr}{\void}
1824
1825 Accessor function to return the password assigned for this class
1826 instance that will be used with the user ID.
1827
1828 Synonymous with \helpref{wxDbConnectInf::GetPassword}{wxdbconnectinfgetpassword}
1829
1830 \membersection{wxDbConnectInf::GetDefaultDir}\label{wxdbconnectinfgetdefaultdir}
1831
1832 \func{const wxChar *}{GetDefaultDir}{\void}
1833
1834 Accessor function to return the default directory in which the datasource's data
1835 table is stored.  This directory is only used for file based datasources like
1836 dBase.  MS-Access does not require this to be set, as the path is set in the
1837 ODBC Administrator for MS-Access.
1838
1839 \membersection{wxDbConnectInf::GetDescription}\label{wxdbconnectinfgetdescription}
1840
1841 \func{const wxChar *}{GetDescription}{\void}
1842
1843 Accessor function to return the description assigned for this class
1844 instance.
1845
1846 NOTE: Description is a FUTURE USE item and is unused currently.
1847
1848 \membersection{wxDbConnectInf::GetDsn}\label{wxdbconnectinfgetdsn}
1849
1850 \func{const wxChar *}{GetDsn}{\void}
1851
1852 Accessor function to return the datasource name assigned for this class
1853 instance.
1854
1855 \membersection{wxDbConnectInf::GetFileType}\label{wxdbconnectinfgetfiletype}
1856
1857 \func{const wxChar *}{GetFileType}{\void}
1858
1859 Accessor function to return the filetype of the ODBC datasource assigned for
1860 this class instance.
1861
1862 NOTE: FileType is a FUTURE USE item and is unused currently.
1863
1864 \membersection{wxDbConnectInf::GetHenv}\label{wxdbconnectinfgethenv}
1865
1866 \func{const HENV}{GetHenv}{\void}
1867
1868 Accessor function to return the SQL environment handle being managed
1869 by this class instance.
1870
1871 \membersection{wxDbConnectInf::GetPassword}\label{wxdbconnectinfgetpassword}
1872
1873 \func{const wxChar *}{GetPassword}{\void}
1874
1875 Accessor function to return the password assigned for this class
1876 instance that will be used with the user ID.
1877
1878 Synonymous with \helpref{wxDbConnectInf::GetAuthStr}{wxdbconnectinfgetauthstr}
1879
1880 \membersection{wxDbConnectInf::GetUid}\label{wxdbconnectinfgetuid}
1881
1882 \func{const wxChar *}{GetUid}{\void}
1883
1884 Accessor function to return the user ID assigned for this class
1885 instance.
1886
1887 \membersection{wxDbConnectInf::GetUserID}\label{wxdbconnectinfgetuserid}
1888
1889 \func{const wxChar *}{GetUserID}{\void}
1890
1891 Accessor function to return the user ID assigned for this class
1892 instance.
1893
1894 \membersection{wxDbConnectInf::SetAuthStr}\label{wxdbconnectinfsetauthstr}
1895
1896 \func{\void}{SetAuthStr}{const wxString \&authstr}
1897
1898 Accessor function to assign the password for this class
1899 instance that will be used with the user ID.
1900
1901 Synonymous with \helpref{wxDbConnectInf::SetPassword}{wxdbconnectinfsetpassword}
1902
1903 \membersection{wxDbConnectInf::SetDefaultDir}\label{wxdbconnectinfsetdefaultdir}
1904
1905 \func{\void}{SetDefaultDir}{const wxString \&defDir}
1906
1907 Accessor function to assign the default directory in which the datasource's data
1908 table is stored.  This directory is only used for file based datasources like
1909 dBase.  MS-Access does not require this to be set, as the path is set in the
1910 ODBC Administrator for MS-Access.
1911
1912 \membersection{wxDbConnectInf::SetDescription}\label{wxdbconnectinfsetdescription}
1913
1914 \func{\void}{SetDescription}{const wxString \&desc}
1915
1916 Accessor function to assign the description assigned for this class
1917 instance.
1918
1919 NOTE: Description is a FUTURE USE item and is unused currently.
1920
1921 \membersection{wxDbConnectInf::SetDsn}\label{wxdbconnectinfsetdsn}
1922
1923 \func{\void}{SetDsn}{const wxString \&dsn}
1924
1925 Accessor function to assign the datasource name for this class instance.
1926
1927 \membersection{wxDbConnectInf::SetFileType}\label{wxdbconnectinfsetfiletype}
1928
1929 \func{\void}{SetFileType}{const wxString \&}
1930
1931 Accessor function to return the filetype of the ODBC datasource assigned for
1932 this class instance.
1933
1934 NOTE: FileType is a FUTURE USE item and is unused currently.
1935
1936 \membersection{wxDbConnectInf::SetHenv}\label{wxdbconnectinfsethenv}
1937
1938 \func{void}{SetHenv}{\param{const HENV }{henv}}
1939
1940 Accessor function to set the SQL environment handle for this class instance.
1941
1942 \membersection{wxDbConnectInf::SetPassword}\label{wxdbconnectinfsetpassword}
1943
1944 \func{\void}{SetPassword}{const wxString \&password}
1945
1946 Accessor function to assign the password for this class
1947 instance that will be used with the user ID.
1948
1949 Synonymous with \helpref{wxDbConnectInf::SetAuthStr}{wxdbconnectinfsetauthstr}
1950
1951 \membersection{wxDbConnectInf::SetUid}\label{wxdbconnectinfsetuid}
1952
1953 \func{\void}{SetUid}{const wxString \&uid}
1954
1955 Accessor function to set the user ID for this class instance.
1956
1957 \membersection{wxDbConnectInf::SetUserID}\label{wxdbconnectinfsetuserid}
1958
1959 \func{\void}{SetUserID}{const wxString \&userID}
1960
1961 Accessor function to assign the user ID for this class instance.
1962
1963 \section{\class{wxDbIdxDef}}\label{wxdbidxdef}
1964
1965 Used in creation of non-primary indexes.  Currently there are no member
1966 functions for this class.
1967
1968 \begin{verbatim}
1969         wxChar  ColName[DB_MAX_COLUMN_NAME_LEN+1]
1970                                   // Name of column
1971         bool    Ascending         // Is index maintained in
1972                                      ASCENDING sequence?
1973 \end{verbatim}
1974
1975 There are no constructors/destructors as of this time, and no member functions.
1976
1977 See the \helpref{database classes overview}{odbcoverview} for
1978 an introduction to using the ODBC classes.
1979
1980 \section{\class{wxDbInf}}\label{wxdbinf}
1981
1982 Contains information regarding the database connection (datasource name,
1983 number of tables, etc).  A pointer to a wxDbTableInf is included in this
1984 class so a program can create a wxDbTableInf array instance to maintain all
1985 information about all tables in the datasource to have all the datasource's
1986 information in one memory structure.
1987
1988 Primarily, this class is used internally by the wxWidgets ODBC classes.
1989
1990 \begin{verbatim}
1991     wxChar        catalog[128+1];
1992     wxChar        schema[128+1];  // typically means owner of table(s)
1993     int           numTables;      // How many tables does this
1994                                      datasource have
1995     wxDbTableInf *pTableInf;      // Equals a new
1996                                      wxDbTableInf[numTables];
1997 \end{verbatim}
1998
1999 The constructor for this class initializes all the values to zero, "", or NULL.
2000
2001 The destructor for this class takes care of deleting the pTableInf member if
2002 it is non-NULL.
2003
2004 See the \helpref{database classes overview}{odbcoverview} for
2005 an introduction to using the ODBC classes.
2006
2007 \membersection{wxDbInf::Initialize}\label{wxdbinfinitialize}
2008
2009 Simply initializes all member variables to a cleared state.  Called by
2010 the constructor automatically.
2011
2012 \section{\class{wxDbTable}}\label{wxdbtable}
2013
2014 A wxDbTable instance provides re-usable access to rows of data in
2015 a table contained within the associated ODBC datasource
2016
2017 See the \helpref{database classes overview}{odbcoverview} for
2018 an introduction to using the ODBC classes.
2019
2020 \wxheading{Include files}
2021
2022 <wx/dbtable.h>\\
2023 <wx/db.h>
2024
2025 \latexignore{\rtfignore{\wxheading{Members}}}
2026 \wxheading{Helper classes and data structures}
2027
2028 The following classes and structs are defined in dbtable.cpp/.h for use
2029 with the wxDbTable class.
2030
2031 \begin{itemize}\itemsep=0pt
2032 \item \helpref{wxDbColDef}{wxdbcoldef}
2033 \item \helpref{wxDbColDataPtr}{wxdbcoldataptr}
2034 \item \helpref{wxDbIdxDef}{wxdbidxdef}
2035 \end{itemize}
2036
2037 \wxheading{Constants}
2038
2039 \begin{verbatim}
2040     wxDB_DEFAULT_CURSOR  Primary cursor normally used for cursor based
2041                          operations.
2042
2043     wxDB_QUERY_ONLY      Used to indicate whether a table that is opened
2044                          is for query only, or if insert/update/deletes
2045                          will be performed on the table.  Less overhead
2046                          (cursors and memory) are allocated for query
2047                          only tables, plus read access times are faster
2048                          with some datasources.
2049
2050     wxDB_ROWID_LEN       [Oracle only] - Used when CanUpdateByRowID()
2051                          is true.  Optimizes updates so they are faster
2052                          by updating on the Oracle-specific ROWID column
2053                          rather than some other index.
2054
2055
2056     wxDB_DISABLE_VIEW    Use to indicate when a database view should not
2057                          be if a table is normally set up to use a view.
2058                          [Currently unsupported.]
2059
2060 \end{verbatim}
2061
2062
2063 \latexignore{\rtfignore{\wxheading{Members}}}
2064
2065 \membersection{wxDbTable::wxDbTable}\label{wxdbtableconstr}
2066
2067 \func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const wxString \&}{tblName},
2068   \param{const UWORD }{numColumns}, \param{const wxString \&}{qryTblName = ""},
2069   \param{bool }{qryOnly = !wxDB\_QUERY\_ONLY}, \param{const wxString \&}{tblPath = ""}}
2070
2071 Default constructor.
2072
2073 \wxheading{Parameters}
2074
2075 \docparam{pwxDb}{Pointer to the wxDb instance to be used by this wxDbTable
2076 instance.}
2077 \docparam{tblName}{The name of the table in the RDBMS.}
2078 \docparam{numColumns}{The number of columns in the table.  (Do NOT include the ROWID
2079 column in the count if using Oracle).}
2080 \docparam{qryTblName}{{\it OPTIONAL}.  The name of the table or view to base
2081 your queries on.  This argument allows you to specify a table/view other than
2082 the base table for this object to base your queries on.  This allows you to
2083 query on a view for example, but all of the INSERT, UPDATE and DELETES will
2084 still be performed on the base table for this wxDbTable object.  Basing your
2085 queries on a view can provide a substantial performance increase in cases where
2086 your queries involve many tables with multiple joins.  Default is "".}
2087 \docparam{qryOnly}{{\it OPTIONAL}.  Indicates whether the table will be
2088 accessible for query purposes only, or should the table create the necessary
2089 cursors to be able to insert, update, and delete data from the table.
2090 Default is !wxDB\_QUERY\_ONLY.}
2091 \docparam{tblPath}{{\it OPTIONAL}.  Some datasources (such as dBase)
2092 require a path to where the table is stored on the system.  Default is "".}
2093
2094 \membersection{wxDbTable::wxDbTable}\label{wxdbtabledestr}
2095
2096 \func{virtual}{\destruct{wxDbTable}}{}
2097
2098 Virtual default destructor.
2099
2100 \membersection{wxDbTable::BuildDeleteStmt}\label{wxdbtablebuilddeletestmt}
2101
2102 \func{void}{BuildDeleteStmt}{\param{wxString \&}{pSqlStmt},
2103 \param{int }{typeOfDel}, \param{const wxString \&}{pWhereClause=""}}
2104
2105 Constructs the full SQL statement that can be used to delete all rows matching
2106 the criteria in the pWhereClause.
2107
2108 \wxheading{Parameters}
2109
2110 \docparam{pSqlStmt}{Pointer to buffer for the SQL statement retrieved.  To be
2111 sure you have adequate space allocated for the SQL statement, allocate
2112 DB\_MAX\_STATEMENT\_LEN bytes.}
2113 \docparam{typeOfDel}{The type of delete statement being performed.  Can be one
2114 of three values: DB\_DEL\_KEYFIELDS, DB\_DEL\_WHERE or DB\_DEL\_MATCHING}
2115 \docparam{pWhereClause}{{\it OPTIONAL}.  If the typeOfDel is DB\_DEL\_WHERE,
2116 then you must also pass in a SQL WHERE clause in this argument.  Default
2117 is "".}
2118
2119 \wxheading{Remarks}
2120
2121 This member function constructs a SQL DELETE statement.  This can be used for
2122 debugging purposes if you are having problems executing your SQL statement.
2123
2124 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2125 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2126 this function.
2127
2128 \membersection{wxDbTable::BuildSelectStmt}\label{wxdbtablebuildselectstmt}
2129
2130 \func{void}{BuildSelectStmt}{\param{wxString \&}{pSqlStmt},
2131 \param{int }{typeOfSelect}, \param{bool }{distinct}}
2132
2133 Constructs the full SQL statement that can be used to select all rows matching
2134 the criteria in the pWhereClause.  This function is called internally in the
2135 wxDbTable class whenever the function \helpref{wxDbTable::Query}{wxdbtablequery}
2136 is called.
2137
2138 NOTE: Only the columns specified in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
2139 statements are included in the list of columns returned by the SQL statement
2140 created by a call to this function.
2141
2142 \wxheading{Parameters}
2143
2144 \docparam{pSqlStmt}{Pointer to storage for the SQL statement retrieved.  To be
2145 sure you have adequate space allocated for the SQL statement, allocate
2146 DB\_MAX\_STATEMENT\_LEN bytes.}
2147 \docparam{typeOfSelect}{The type of select statement being performed.  Can be
2148 one of four values: DB\_SELECT\_KEYFIELDS, DB\_SELECT\_WHERE, DB\_SELECT\_MATCHING
2149 or DB\_SELECT\_STATEMENT.}
2150 \docparam{distinct}{Whether to select distinct records only.}
2151
2152 \wxheading{Remarks}
2153
2154 This member function constructs a SQL SELECT statement.  This can be used for
2155 debugging purposes if you are having problems executing your SQL statement.
2156
2157 WHERE and FROM clauses specified using
2158 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2159 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2160 this function.
2161
2162 \membersection{wxDbTable::BuildUpdateStmt}\label{wxdbtablebuildupdatestmt}
2163
2164 \func{void}{BuildUpdateStmt}{\param{wxString \&}{pSqlStmt}, \param{int }{typeOfUpd},
2165 \param{const wxString \&}{pWhereClause=""}}
2166
2167 Constructs the full SQL statement that can be used to update all rows matching
2168 the criteria in the pWhereClause.
2169
2170 If typeOfUpd is DB\_UPD\_KEYFIELDS, then the current values in the bound columns
2171 are used to determine which row(s) in the table are to be updated. The
2172 exception to this is when a datasource supports ROW IDs (Oracle).  The ROW ID
2173 column is used for efficiency purposes when available.
2174
2175 NOTE: Only the columns specified in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
2176 statements are included in the list of columns updated by the SQL statement
2177 created by a call to this function.  Any column definitions that were defined
2178 as being non-updateable will be excluded from the SQL UPDATE statement created
2179 by this function.
2180
2181 \wxheading{Parameters}
2182
2183 \docparam{pSqlStmt}{Pointer to storage for the SQL statement retrieved.  To be
2184 sure you have adequate space allocated for the SQL statement, allocate
2185 DB\_MAX\_STATEMENT\_LEN bytes.}
2186 \docparam{typeOfUpd}{The type of update statement being performed.  Can be one
2187 of two values: DB\_UPD\_KEYFIELDS or DB\_UPD\_WHERE.}
2188 \docparam{pWhereClause}{{\it OPTIONAL}.  If the typeOfUpd is DB\_UPD\_WHERE,
2189 then you must also pass in a SQL WHERE clause in this argument. Default is "".}
2190
2191 \wxheading{Remarks}
2192
2193 This member function allows you to see what the SQL UPDATE statement looks like
2194 that the ODBC class library builds.  This can be used for debugging purposes if
2195 you are having problems executing your SQL statement.
2196
2197 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2198 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2199 this function.
2200
2201 \membersection{wxDbTable::BuildWhereStmt}\label{wxdbtablebuildwherestmt}
2202
2203 \func{void}{BuildSelectStmt}{\param{wxString \&}{pWhereClause},
2204 \param{int }{typeOfWhere}, \param{const wxString \&}{qualTableName=""},
2205 \param{bool }{useLikeComparison=false}}
2206
2207 Constructs the portion of a SQL statement which would follow the word 'WHERE'
2208 in a SQL statement to be passed to the datasource.  The returned string
2209 does NOT include the word 'WHERE'.
2210
2211 \wxheading{Parameters}
2212
2213 \docparam{pWhereClause}{Pointer to storage for the SQL statement retrieved.
2214 To be sure you have adequate space allocated for the SQL statement, allocate
2215 DB\_MAX\_STATEMENT\_LEN bytes.}
2216 \docparam{typeOfWhere}{The type of where clause to generate.  Can be one of
2217 two values:  DB\_WHERE\_KEYFIELDS or DB\_WHERE\_MATCHING.}
2218 \docparam{qualTableName}{{\it OPTIONAL}.  Prepended to all base table
2219 column names.  For use when a FROM clause has been specified with the
2220 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause},
2221 to clarify which table a column name reference belongs to.  Default is "".}
2222 \docparam{useLikeComparison}{{\it OPTIONAL}.  Should the constructed WHERE
2223 clause utilize the LIKE comparison operator.  If false, then the '='
2224 operator is used.  Default is false.}
2225
2226 \wxheading{Remarks}
2227
2228 This member function allows you to see what the SQL WHERE clause looks like
2229 that the ODBC class library builds.  This can be used for debugging purposes
2230 if you are having problems executing your own SQL statements.
2231
2232 If using 'typeOfWhere' set to DB\_WHERE\_MATCHING, any bound columns currently
2233 containing a NULL value are not included in the WHERE clause's list of
2234 columns to use in the comparison.
2235
2236 \membersection{wxDbTable::CanSelectForUpdate}\label{wxdbtablecanselectforupdate}
2237
2238 \func{bool}{CanSelectForUpdate}{\void}
2239
2240 Use this function to determine if the datasource supports SELECT ... FOR UPDATE.
2241 When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement,
2242 all records {\it retrieved} (not just queried, but actually retrieved using
2243 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}, etc) from the result set are
2244 locked.
2245
2246 \wxheading{Remarks}
2247
2248 Not all datasources support the "FOR UPDATE" clause, so you must use this
2249 member function to determine if the datasource currently connected to supports
2250 this behavior or not before trying to select using "FOR UPDATE".
2251
2252 If the wxDbTable instance was created with the parameter wxDB\_QUERY\_ONLY, then
2253 this function will return false.  For all known databases which do not support
2254 the FOR UPDATE clause, this function will return false also.
2255
2256 \membersection{wxDbTable::CanUpdateByROWID}\label{wxdbtablecanupdatebyrowid}
2257
2258 \func{bool}{CanUpdateByROWID}{\void}
2259
2260 CURRENTLY ONLY POSSIBLE IF USING ORACLE.
2261
2262 --- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV 1 2000 - gt
2263
2264 Every Oracle table has a hidden column named ROWID.  This is a pointer to the
2265 physical location of the record in the datasource and allows for very fast
2266 updates and deletes.  The key is to retrieve this ROWID during your query so
2267 it is available during an update or delete operation.
2268
2269 Use of the ROWID feature is always handled by the class library except in the
2270 case of \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.  Since
2271 you are passing in the SQL SELECT statement,
2272 it is up to you to include the ROWID column in your query.  If you do not,
2273 the application will still work, but may not be as optimized.  The ROWID is
2274 always the last column in the column list in your SQL SELECT statement.
2275 The ROWID is not a column in the normal sense and should not be considered
2276 part of the column definitions for the wxDbTable object.
2277
2278 \wxheading{Remarks}
2279
2280 The decision to include the ROWID in your SQL SELECT statement must be
2281 deferred until runtime since it depends on whether you are connected
2282 to an Oracle datasource or not.
2283
2284 \wxheading{Example}
2285
2286 \begin{verbatim}
2287     // Incomplete code sample
2288     wxDbTable parts;
2289     .....
2290     if (parts.CanUpdByROWID())
2291     {
2292         // Note that the ROWID column must always be the last column selected
2293         sqlStmt = "SELECT PART_NO, PART_DESC, ROWID" FROM PARTS";
2294     }
2295     else
2296         sqlStmt = "SELECT PART_NO, PART_DESC FROM PARTS";
2297 \end{verbatim}
2298
2299
2300 \membersection{wxDbTable::ClearMemberVar}\label{wxdbtableclearmembervar}
2301
2302 \func{void}{ClearMemberVar}{\param{UWORD }{colNo}, \param{bool }{setToNull=false}}
2303
2304 Same as \helpref{wxDbTable::ClearMemberVars}{wxdbtableclearmembervars} except
2305 that this function clears only the specified column of its values, and
2306 optionally sets the column to be a NULL column.
2307
2308 \docparam{colNo}{Column number that is to be cleared.  This number (between 0
2309 and (noCols-1)) is the index of the column definition created using the
2310 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} function.}
2311 \docparam{setToNull}{{\it OPTIONAL}.  Indicates whether the column should be
2312 flagged as being a NULL value stored in the bound memory variable.  If true,
2313 then any value stored in the bound member variable is cleared.  Default is
2314 false.}
2315
2316 \membersection{wxDbTable::ClearMemberVars}\label{wxdbtableclearmembervars}
2317
2318 \func{void}{ClearMemberVars}{\param{bool }{setToNull=false}}
2319
2320 Initializes all bound columns of the wxDbTable instance to zero.  In the case
2321 of a string, zero is copied to the first byte of the string.
2322
2323 \docparam{setToNull}{{\it OPTIONAL}.  Indicates whether all columns should be
2324 flagged as having a NULL value stored in the bound memory variable.  If true,
2325 then any value stored in the bound member variable is cleared.  Default is
2326 false.}
2327
2328 \wxheading{Remarks}
2329
2330 This is useful before calling functions such as
2331 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2332 \helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching} since these
2333 functions build their WHERE clauses from non-zero columns.  To call either
2334 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2335 \helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching} use this sequence:
2336
2337 \begin{verbatim}
2338 1)  ClearMemberVars()
2339 2)  Assign columns values you wish to match on
2340 3)  Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
2341 \end{verbatim}
2342
2343 \membersection{wxDbTable::CloseCursor}\label{wxdbtableclosecursor}
2344
2345 \func{bool}{CloseCursor}{\param{HSTMT}{cursor}}
2346
2347 Closes the specified cursor associated with the wxDbTable object.
2348
2349 \wxheading{Parameters}
2350
2351 \docparam{cursor}{The cursor to be closed.}
2352
2353 \wxheading{Remarks}
2354
2355 Typically handled internally by the ODBC class library, but may be used by the
2356 programmer if desired.
2357
2358 \normalbox{DO NOT CLOSE THE wxDB\_DEFAULT\_CURSOR!}
2359
2360 \membersection{wxDbTable::Count}\label{wxdbtablecount}
2361
2362 \func{ULONG }{Count}{\param{const wxString \&}{args="*"}}
2363
2364 Returns the number of records which would be in the result set using the
2365 current query parameters specified in the WHERE and FROM clauses.
2366
2367 \wxheading{Parameters}
2368
2369 \docparam{args}{{\it OPTIONAL}.  This argument allows the use of the
2370 DISTINCT keyword against a column name to cause the returned count to
2371 only indicate the number of rows in the result set that have a unique
2372 value in the specified column.  An example is shown below.  Default is "*",
2373 meaning a count of the total number of rows matching is returned, regardless
2374 of uniqueness.}
2375
2376 \wxheading{Remarks}
2377
2378 This function can be called before or after an actual query to obtain the
2379 count of records in the result set.  Count() uses its own cursor, so result
2380 set cursor positioning is not affected by calls to Count().
2381
2382 WHERE and FROM clauses specified using
2383 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2384 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} ARE used by
2385 this function.
2386
2387 \wxheading{Example}
2388
2389 \begin{verbatim}
2390
2391     USERS TABLE
2392
2393     FIRST_NAME      LAST_NAME
2394     -----------     ----------
2395     John            Doe
2396     Richard         Smith
2397     Michael         Jones
2398     John            Carpenter
2399
2400     // Incomplete code sample
2401     wxDbTable users;
2402     .....
2403     users.SetWhereClause("");
2404
2405     // This Count() will return 4, as there are four users listed above
2406     // that match the query parameters
2407     totalNumberOfUsers = users.Count();
2408
2409     // This Count() will return 3, as there are only 3 unique first names
2410     // in the table above - John, Richard, Michael.
2411     totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
2412 \end{verbatim}
2413
2414 \membersection{wxDbTable::CreateIndex}\label{wxdbtablecreateindex}
2415
2416 \func{bool}{CreateIndex}{\param{const wxString \&}{idxName}, \param{bool }{unique},
2417 \param{UWORD }{noIdxCols}, \param{wxDbIdxDef *}{pIdxDefs},
2418 \param{bool }{attemptDrop=true}}
2419
2420 This member function allows you to create secondary (non primary) indexes on
2421 your tables.  You first create your table, normally specifying a primary
2422 index, and then create any secondary indexes on the table.  Indexes in
2423 relational model are not required.  You do not need indexes to look up records
2424 in a table or to join two tables together.  In the relational model, indexes,
2425 if available, provide a quicker means to look up data in a table.  To enjoy
2426 the performance benefits of indexes, the indexes must be defined on the
2427 appropriate columns and your SQL code must be written in such a way as to
2428 take advantage of those indexes.
2429
2430 \wxheading{Parameters}
2431
2432 \docparam{idxName}{Name of the Index.  Name must be unique within the table
2433 space of the datasource.}
2434 \docparam{unique}{Indicates if this index is unique.}
2435 \docparam{noIdxCols}{Number of columns in the index.}
2436 \docparam{pIdxDefs}{A pointer to an array wxDbIdxDef structures. }
2437 \docparam{attemptDrop}{{\it OPTIONAL}.  Indicates if the function should try
2438 to execute a \helpref{wxDbTable::DropIndex}{wxdbtabledropindex} on the index
2439 name provided before trying to create the index name.  Default is true.}
2440
2441 \wxheading{Remarks}
2442
2443 The first parameter, index name, must be unique and should be given a
2444 meaningful name.  Common practice is to include the table name as a prefix
2445 in the index name (e.g. For table PARTS, you might want to call your index
2446 PARTS\_IDX1).  This will allow you to easily view all
2447 of the indexes defined for a given table grouped together alphabetically.
2448
2449 The second parameter indicates if the index is unique or not.  Uniqueness
2450 is enforced at the RDBMS level preventing rows which would have duplicate
2451 indexes from being inserted into the table when violating a unique index's
2452 uniqueness.
2453
2454 In the third parameter, specify how many columns are in your index.  This
2455 number must match the number of columns defined in the 'pIdxDefs' parameter.
2456
2457 The fourth parameter specifies which columns make up the index using the
2458 wxDbIdxDef structure.  For each column in the index, you must specify two
2459 things, the column name and the sort order (ascending / descending).  See
2460 the example below to see how to build and pass in the wxDbIdxDef structure.
2461
2462 The fifth parameter is provided to handle the differences in datasources as
2463 to whether they will automatically overwrite existing indexes with the same
2464 name or not.  Some datasources require that the existing index must be dropped
2465 first, so this is the default behavior.
2466
2467 Some datasources (MySQL, and possibly others) require columns which are to be
2468 part of an index to be defined as NOT NULL.  When this function is called, if
2469 a column is not defined to be NOT NULL, a call to this function will modify
2470 the column definition to change any columns included in the index to be
2471 NOT NULL.  In this situation, if a NULL value already exists in one of the
2472 columns that is being modified, creation of the index will fail.
2473
2474 PostGres is unable to handle index definitions which specify whether the index
2475 is ascending or descending, and defaults to the system default when the index
2476 is created.
2477
2478 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2479 after executing this function.
2480
2481 \wxheading{Example}
2482
2483 \begin{verbatim}
2484     // Create a secondary index on the PARTS table
2485     wxDbIdxDef  idxDef[2];  // 2 columns make up the index
2486
2487     wxStrcpy(idxDef[0].ColName, "PART_DESC");  // Column 1
2488     idxDef[0].Ascending = true;
2489
2490     wxStrcpy(idxDef[1].ColName, "SERIAL_NO");  // Column 2
2491     idxDef[1].Ascending = false;
2492
2493     // Create a name for the index based on the table's name
2494     wxString indexName;
2495     indexName.Printf("%s_IDX1",parts->GetTableName());
2496     parts->CreateIndex(indexName, true, 2, idxDef);
2497 \end{verbatim}
2498
2499 \membersection{wxDbTable::CreateTable}\label{wxdbtablecreatetable}
2500
2501 \func{bool}{CreateTable}{\param{bool }{attemptDrop=true}}
2502
2503 Creates a table based on the definitions previously defined for this
2504 wxDbTable instance.
2505
2506 \wxheading{Parameters}
2507
2508 \docparam{attemptDrop}{{\it OPTIONAL}.  Indicates whether the driver should
2509 attempt to drop the table before trying to create it.  Some datasources will
2510 not allow creation of a table if the table already exists in the table space
2511 being used.  Default is true.}
2512
2513 \wxheading{Remarks}
2514
2515 This function creates the table and primary index (if any) in the table space
2516 associated with the connected datasource.  The owner of these objects will
2517 be the user id that was given when \helpref{wxDb::Open}{wxdbopen} was called.
2518 The objects will be created in the default schema/table space for that user.
2519
2520 In your derived wxDbTable object constructor, the columns and primary index
2521 of the table are described through the \helpref{wxDbColDef}{wxdbcoldef} structure.
2522 \helpref{wxDbTable::CreateTable}{wxdbtablecreatetable} uses this information
2523 to create the table and to add the primary index.  See
2524 \helpref{wxDbTable}{wxdbtable} ctor and wxDbColDef description for additional
2525 information on describing the columns of the table.
2526
2527 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2528 after executing this function.
2529
2530 \membersection{wxDbTable::DB\_STATUS}\label{wxdbtabledbstatus}
2531
2532 \func{bool}{DB\_STATUS}{\void}
2533
2534 Accessor function that returns the wxDb private member variable DB\_STATUS for
2535 the database connection used by this instance of wxDbTable.
2536
2537 \membersection{wxDbTable::Delete}\label{wxdbtabledelete}
2538
2539 \func{bool}{Delete}{\void}
2540
2541 Deletes the row from the table indicated by the current cursor.
2542
2543 \wxheading{Remarks}
2544
2545 Use \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst},
2546 \helpref{wxDbTable::GetLast}{wxdbtablegetlast},
2547 \helpref{wxDbTable::GetNext}{wxdbtablegetnext} or
2548 \helpref{wxDbTable::GetPrev}{wxdbtablegetprev} to position the cursor to
2549 a valid record.  Once positioned on a record, call this function to delete
2550 the row from the table.
2551
2552 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2553 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
2554 this function to commit or rollback the deletion.
2555
2556 NOTE: Most datasources have a limited size "rollback" segment.  This means
2557 that it is only possible to insert/update/delete a finite number of rows
2558 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2559 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2560 segment varies from database to database, and is user configurable in
2561 most databases.  Therefore it is usually best to try to perform a commit
2562 or rollback at relatively small intervals when processing a larger number
2563 of actions that insert/update/delete rows in a table.
2564
2565 \membersection{wxDbTable::DeleteCursor}\label{wxdbtabledeletecursor}
2566
2567 \func{bool}{DeleteCursor}{\param{HSTMT *}{hstmtDel}}
2568
2569 Allows a program to delete a cursor.
2570
2571 \wxheading{Parameters}
2572
2573 \docparam{hstmtDel}{Handle of the cursor to delete.}
2574
2575 \wxheading{Remarks}
2576
2577 For default cursors associated with the instance of wxDbTable, it is not
2578 necessary to specifically delete the cursors.  This is automatically done
2579 in the wxDbTable destructor.
2580
2581 NOTE: If the cursor could not be deleted for some reason, an error is logged
2582 indicating the reason.  Even if the cursor could not be deleted, the HSTMT
2583 that is passed in is deleted, and the pointer is set to NULL.
2584
2585 \normalbox{DO NOT DELETE THE wxDB\_DEFAULT\_CURSOR!}
2586
2587 \membersection{wxDbTable::DeleteMatching}\label{wxdbtabledeletematching}
2588
2589 \func{bool}{DeleteMatching}{\void}
2590
2591 This member function allows you to delete records from your wxDbTable object
2592 by specifying the data in the columns to match on.
2593
2594 \wxheading{Remarks}
2595
2596 To delete all users with a first name of "JOHN", do the following:
2597
2598 \begin{enumerate}\itemsep=0pt
2599 \item Clear all "columns" using wxDbTable::ClearMemberVars().
2600 \item Set the FIRST\_NAME column equal to "JOHN".
2601 \item Call wxDbTable::DeleteMatching().
2602 \end{enumerate}
2603
2604 The WHERE clause is built by the ODBC class library based on all non-NULL
2605 columns.  This allows deletion of records by matching on any column(s) in
2606 your wxDbTable instance, without having to write the SQL WHERE clause.
2607
2608 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2609 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
2610 this function to commit or rollback the deletion.
2611
2612 NOTE: Row(s) should be locked before deleting them to make sure they are
2613 not already in use.  This can be achieved by calling
2614 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching},
2615 and then retrieving the records, locking each as you go (assuming FOR UPDATE
2616 is allowed on the datasource).  After the row(s) have been successfully locked,
2617 call this function.
2618
2619 NOTE: Most datasources have a limited "rollback" segment.  This means
2620 that it is only possible to insert/update/delete a finite number of rows
2621 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2622 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2623 segment varies from database to database, and is user configurable in
2624 most databases.  Therefore it is usually best to try to perform a commit
2625 or rollback at relatively small intervals when processing a larger number
2626 of actions that insert/update/delete rows in a table.
2627
2628 \wxheading{Example}
2629
2630 \begin{verbatim}
2631     // Incomplete code sample to delete all users with a first name
2632     // of "JOHN"
2633     users.ClearMemberVars();
2634     wxStrcpy(users.FirstName,"JOHN");
2635     users.DeleteMatching();
2636 \end{verbatim}
2637
2638
2639 \membersection{wxDbTable::DeleteWhere}\label{wxdbtabledeletewhere}
2640
2641 \func{bool}{DeleteWhere}{\param{const wxString \&}{pWhereClause}}
2642
2643 Deletes all rows from the table which match the criteria specified in the
2644 WHERE clause that is passed in.
2645
2646 \wxheading{Parameters}
2647
2648 \docparam{pWhereClause}{SQL WHERE clause.  This WHERE clause determines which
2649 records will be deleted from the table interfaced through the wxDbTable
2650 instance.  The WHERE clause passed in must be compliant with the SQL 92
2651 grammar.  Do not include the keyword 'WHERE'
2652 }
2653
2654 \wxheading{Remarks}
2655
2656 This is the most powerful form of the wxDbTable delete functions.  This
2657 function gives access to the full power of SQL.  This function can be used
2658 to delete records by passing a valid SQL WHERE clause.  Sophisticated
2659 deletions can be performed based on multiple criteria using the full
2660 functionality of the SQL language.
2661
2662 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} must be called after use of
2663 this function to commit the deletions.
2664
2665 Note: This function is limited to deleting records from the table associated
2666 with this wxDbTable object only.  Deletions on joined tables is not possible.
2667
2668 NOTE: Most datasources have a limited size "rollback" segment.  This means
2669 that it is only possible to insert/update/delete a finite number of rows
2670 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2671 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2672 segment varies from database to database, and is user configurable in
2673 most databases.  Therefore it is usually best to try to perform a commit
2674 or rollback at relatively small intervals when processing a larger number
2675 of actions that insert/update/delete rows in a table.
2676
2677 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
2678 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
2679 this function.
2680
2681 \wxheading{Example}
2682
2683 \begin{verbatim}
2684     // Delete parts 1 thru 10 from containers 'X', 'Y' and 'Z' that
2685     // are magenta in color
2686     parts.DeleteWhere("(PART_NUMBER BETWEEN 1 AND 10) AND \
2687                         CONTAINER IN ('X', 'Y', 'Z') AND \
2688                         UPPER(COLOR) = 'MAGENTA'");
2689 \end{verbatim}
2690
2691
2692 \membersection{wxDbTable::DropIndex}\label{wxdbtabledropindex}
2693
2694 \func{bool}{DropIndex}{\param{const wxString \&}{idxName}}
2695
2696 Allows an index on the associated table to be dropped (deleted) if the user
2697 login has sufficient privileges to do so.
2698
2699 \wxheading{Parameters}
2700
2701 \docparam{idxName}{Name of the index to be dropped.}
2702
2703 \wxheading{Remarks}
2704
2705 If the index specified in the 'idxName' parameter does not exist, an error
2706 will be logged, and the function will return a result of false.
2707
2708 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2709 after executing this function.
2710
2711 \membersection{wxDbTable::DropTable}\label{wxdbtabledroptable}
2712
2713 \func{bool}{DropTable}{\void}
2714
2715 Deletes the associated table if the user has sufficient privileges to do so.
2716
2717 \wxheading{Remarks}
2718
2719 This function returns true if the table does not exist, but only for
2720 supported databases (see \helpref{wxDb::Dbms}{wxdbdbms}).  If a datasource
2721 is not specifically supported, and this function is called, the function
2722 will return false.
2723
2724 Most datasources/ODBC drivers will delete any indexes associated with the
2725 table automatically, and others may not.  Check the documentation for your
2726 database to determine the behavior.
2727
2728 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2729 after executing this function.
2730
2731 \membersection{wxDbTable::From}\label{wxdbtablefrom}
2732
2733 \func{const wxString \&}{From}{}
2734
2735 \func{void}{From}{\param{const wxString \&}{From}}
2736
2737 Accessor function for the private class member wxDbTable::from.  Can be used
2738 as a synonym for \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
2739 (the first form of this function) or
2740 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} (the second form
2741 of this function).
2742
2743 \wxheading{Parameters}
2744
2745 \docparam{From}{A comma separated list of table names that are to be outer
2746 joined with the base table's columns so that the joined table's columns
2747 may be returned in the result set or used as a portion of a comparison with
2748 the base table's columns.  NOTE that the base tables name must NOT be included
2749 in the FROM clause, as it is automatically included by the wxDbTable class
2750 in constructing query statements.}
2751
2752 \wxheading{Return value}
2753
2754 The first form of this function returns the current value of the wxDbTable
2755 member variable ::from.
2756
2757 The second form of the function has no return value, as it will always set
2758 the from clause successfully.
2759
2760 \wxheading{See also}
2761
2762 \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause},
2763 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
2764
2765
2766 \membersection{wxDbTable::GetColDefs}\label{wxdbtablegetcoldefs}
2767
2768 \func{wxDbColDef *}{GetColDefs}{}
2769
2770 Accessor function that returns a pointer to the array of column definitions
2771 that are bound to the columns that this wxDbTable instance is associated
2772 with.
2773
2774 To determine the number of elements pointed to by the returned
2775 \helpref{wxDbColDef}{wxdbcoldef} pointer, use the
2776 \helpref{wxDbTable::GetNumberOfColumns}{wxdbtablegetnumberofcolumns} function.
2777
2778 \wxheading{Remarks}
2779
2780 These column definitions must not be manually redefined after they have been
2781 set.
2782
2783 \membersection{wxDbTable::GetCursor}\label{wxdbtablegetcursor}
2784
2785 \func{HSTMT}{GetCursor}{\void}
2786
2787 Returns the HSTMT value of the current cursor for this wxDbTable object.
2788
2789 \wxheading{Remarks}
2790
2791 This function is typically used just before changing to use a different cursor
2792 so that after the program is finished using the other cursor, the current
2793 cursor can be set back to being the cursor in use.
2794
2795 \wxheading{See also}
2796
2797 \helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}, \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor}
2798
2799 \membersection{wxDbTable::GetDb}\label{wxdbtablegetdb}
2800
2801 \func{wxDb *}{GetDb}{}
2802
2803 Accessor function for the private member variable pDb which is a pointer to
2804 the datasource connection that this wxDbTable instance uses.
2805
2806 \membersection{wxDbTable::GetFirst}\label{wxdbtablegetfirst}
2807
2808 \func{bool}{GetFirst}{\void}
2809
2810 Retrieves the FIRST row in the record set as defined by the current query.
2811 Before retrieving records, a query must be performed using
2812 \helpref{wxDbTable::Query}{wxdbtablequery},
2813 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2814 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2815 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2816
2817 \wxheading{Remarks}
2818
2819 This function can only be used if the datasource connection used by the
2820 wxDbTable instance was created with FwdOnlyCursors set to false.  If the
2821 connection does not allow backward scrolling cursors, this function will
2822 return false, and the data contained in the bound columns will be undefined.
2823
2824 \wxheading{See also}
2825
2826 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
2827
2828 \membersection{wxDbTable::GetFromClause}\label{wxdbtablegetfromclause}
2829
2830 \func{const wxString \&}{GetFromClause}{}
2831
2832 Accessor function that returns the current FROM setting assigned with the
2833 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
2834
2835 \wxheading{See also}
2836
2837 \helpref{wxDbTable::From}{wxdbtablefrom}
2838
2839 \membersection{wxDbTable::GetLast}\label{wxdbtablegetlast}
2840
2841 \func{bool}{GetLast}{\void}
2842
2843 Retrieves the LAST row in the record set as defined by the current query.
2844 Before retrieving records, a query must be performed using
2845 \helpref{wxDbTable::Query}{wxdbtablequery},
2846 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2847 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2848 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2849
2850 \wxheading{Remarks}
2851
2852 This function can only be used if the datasource connection used by the
2853 wxDbTable instance was created with FwdOnlyCursors set to false.  If the
2854 connection does not allow backward scrolling cursors, this function will
2855 return false, and the data contained in the bound columns will be undefined.
2856
2857 \wxheading{See also}
2858
2859 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
2860
2861 \membersection{wxDbTable::GetNewCursor}\label{wxdbtablegetnewcursor}
2862
2863 \func{HSTMT *}{GetNewCursor}{\param{bool }{setCursor=false},
2864 \param{bool }{bindColumns=true}}
2865
2866 This function will create a new cursor that can be used to access the table
2867 being referenced by this wxDbTable instance, or to execute direct SQL commands
2868 on without affecting the cursors that are already defined and possibly
2869 positioned.
2870
2871 \wxheading{Parameters}
2872
2873 \docparam{setCursor}{{\it OPTIONAL}.  Should this new cursor be set to be the
2874 current cursor after successfully creating the new cursor.  Default is false.}
2875 \docparam{bindColumns}{{\it OPTIONAL}.  Should this new cursor be bound to all
2876 the memory variables that the default cursor is bound to.  Default is true.}
2877
2878 \wxheading{Remarks}
2879
2880 This new cursor must be closed using
2881 \helpref{wxDbTable::DeleteCursor}{wxdbtabledeletecursor}
2882 by the calling program before the wxDbTable instance is deleted, or both
2883 memory and resource leaks will occur.
2884
2885 \membersection{wxDbTable::GetNext}\label{wxdbtablegetnext}
2886
2887 \func{bool}{GetNext}{\void}
2888
2889 Retrieves the NEXT row in the record set after the current cursor position
2890 as defined by the current query.  Before retrieving records, a query must be
2891 performed using \helpref{wxDbTable::Query}{wxdbtablequery},
2892 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2893 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2894 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2895
2896 \wxheading{Return value}
2897
2898 This function returns false when the current cursor has reached the end of
2899 the result set.  When false is returned, data in the bound columns is
2900 undefined.
2901
2902 \wxheading{Remarks}
2903
2904 This function works with both forward and backward scrolling cursors.
2905
2906 \wxheading{See also}
2907 \helpref{wxDbTable::++}{wxdbtableplusplus}
2908
2909 \membersection{wxDbTable::GetNumberOfColumns}\label{wxdbtablegetnumberofcolumns}
2910
2911 \func{UWORD }{GetNumberOfColumns}{}
2912
2913 Accessor function that returns the number of columns that are statically
2914 bound for access by the wxDbTable instance.
2915
2916 \membersection{wxDbTable::GetOrderByClause}\label{wxdbtablegetorderbyclause}
2917
2918 \func{const wxString \&}{GetOrderByClause}{}
2919
2920 Accessor function that returns the current ORDER BY setting assigned with
2921 the \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}.
2922
2923 \wxheading{See also}
2924
2925 \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
2926
2927 \membersection{wxDbTable::GetPrev}\label{wxdbtablegetprev}
2928
2929 \func{bool}{GetPrev}{\void}
2930
2931 Retrieves the PREVIOUS row in the record set before the current cursor
2932 position as defined by the current query.  Before retrieving records, a
2933 query must be performed using \helpref{wxDbTable::Query}{wxdbtablequery},
2934 \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
2935 \helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
2936 \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
2937
2938 \wxheading{Return value}
2939
2940 This function returns false when the current cursor has reached the beginning
2941 of the result set and there are now other rows prior to the cursors current
2942 position.  When false is returned, data in the bound columns is undefined.
2943
2944 \wxheading{Remarks}
2945
2946 This function can only be used if the datasource connection used by the
2947 wxDbTable instance was created with FwdOnlyCursors set to false.  If the
2948 connection does not allow backward scrolling cursors, this function will
2949 return false, and the data contained in the bound columns will be undefined.
2950
2951 \wxheading{See also}
2952
2953 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors},
2954 \helpref{wxDbTable::--}{wxdbtableminusminus}
2955
2956 \membersection{wxDbTable::GetQueryTableName}\label{wxdbtablegetquerytablename}
2957
2958 \func{const wxString \&}{GetQueryTableName}{}
2959
2960 Accessor function that returns the name of the table/view that was indicated
2961 as being the table/view to query against when this wxDbTable instance was
2962 created.
2963
2964 \wxheading{See also}
2965
2966 \helpref{wxDbTable constructor}{wxdbtableconstr}
2967
2968 \membersection{wxDbTable::GetRowNum}\label{wxdbtablegetrownum}
2969
2970 \func{UWORD}{GetRowNum}{\void}
2971
2972 Returns the ODBC row number for performing positioned updates and deletes.
2973
2974 \wxheading{Remarks}
2975
2976 This function is not being used within the ODBC class library and may be a
2977 candidate for removal if no use is found for it.
2978
2979 Row number with some datasources/ODBC drivers is the position in the result set,
2980 while in others it may be a physical position in the database.  Check your
2981 database documentation to find out which behavior is supported.
2982
2983 \membersection{wxDbTable::GetTableName}\label{wxdbtablegettablename}
2984
2985 \func{const wxString \&}{GetTableName}{}
2986
2987 Accessor function that returns the name of the table that was indicated
2988 as being the table that this wxDbTable instance was associated with.
2989
2990 \membersection{wxDbTable::GetTablePath}\label{wxdbtablegettablepath}
2991
2992 \func{const wxString \&}{GetTablePath}{}
2993
2994 Accessor function that returns the path to the data table that was indicated
2995 during creation of this wxDbTable instance.
2996
2997 \wxheading{Remarks}
2998
2999 Currently only applicable to dBase and MS-Access datasources.
3000
3001 \membersection{wxDbTable::GetWhereClause}\label{wxdbtablegetwhereclause}
3002
3003 \func{const wxString \&}{GetWhereClause}{}
3004
3005 Accessor function that returns the current WHERE setting assigned with the
3006 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3007
3008 \wxheading{See also}
3009
3010 \helpref{wxDbTable::Where}{wxdbtablewhere}
3011
3012 \membersection{wxDbTable::Insert}\label{wxdbtableinsert}
3013
3014 \func{int }{Insert}{\void}
3015
3016 Inserts a new record into the table being referenced by this wxDbTable
3017 instance.  The values in the member variables of the wxDbTable instance are
3018 inserted into the columns of the new row in the database.
3019
3020 \wxheading{Return value}
3021
3022 \begin{verbatim}
3023     DB_SUCCESS              Record inserted successfully (value = 1)
3024
3025     DB_FAILURE              Insert failed (value = 0)
3026
3027     DB_ERR_INTEGRITY_CONSTRAINT_VIOL
3028                             The insert failed due to an integrity
3029                             constraint violation (duplicate non-unique
3030                             index entry) is attempted.
3031 \end{verbatim}
3032
3033 \wxheading{Remarks}
3034
3035 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3036 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3037 this function to commit or rollback the insertion.
3038
3039 \wxheading{Example}
3040
3041 \begin{verbatim}
3042     // Incomplete code snippet
3043     wxStrcpy(parts->PartName, "10");
3044     wxStrcpy(parts->PartDesc, "Part #10");
3045     parts->Qty = 1000;
3046     RETCODE retcode = parts->Insert();
3047     switch(retcode)
3048     {
3049         case DB_SUCCESS:
3050             parts->GetDb()->CommitTrans();
3051             return(true);
3052         case DB_ERR_INTEGRITY_CONSTRAINT_VIOL:
3053             // Current data would result in a duplicate key
3054             // on one or more indexes that do not allow duplicates
3055             parts->GetDb()->RollbackTrans();
3056             return(false);
3057         default:
3058             // Insert failed for some unexpected reason
3059             parts->GetDb()->RollbackTrans();
3060             return(false);
3061     }
3062 \end{verbatim}
3063
3064 \membersection{wxDbTable::IsColNull}\label{wxdbtableiscolnull}
3065
3066 \func{bool }{IsColNull}{\param{UWORD }{colNo}} const
3067
3068 Used primarily in the ODBC class library to determine if a column value is
3069 set to "NULL".  Works for all data types supported by the ODBC class library.
3070
3071 \wxheading{Parameters}
3072
3073 \docparam{colNo}{The column number of the bound column as defined by the
3074 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
3075 calls which defined the columns accessible to this wxDbTable instance.}
3076
3077 \wxheading{Remarks}
3078
3079 NULL column support is currently not fully implemented as of wxWidgets 2.4.
3080
3081 \membersection{wxDbTable::IsCursorClosedOnCommit}\label{wxdbtableiscursorclosedoncommit}
3082
3083 \func{bool }{IsCursorClosedOnCommit}{\void}
3084
3085 Accessor function to return information collected during the opening of the
3086 datasource connection that is used by this wxDbTable instance.  The result
3087 returned by this function indicates whether an implicit closing of the cursor is
3088 done after a commit on the database connection.
3089
3090 \wxheading{Return value}
3091
3092 Returns true if the cursor associated with this wxDbTable object is closed
3093 after a commit or rollback operation.  Returns false otherwise.
3094
3095 \wxheading{Remarks}
3096
3097 If more than one wxDbTable instance used the same database connection, all cursors
3098 which use the database connection are closed on the commit if this function
3099 indicates true.
3100
3101 \membersection{wxDbTable::IsQueryOnly}\label{wxdbtableisqueryonly}
3102
3103 \func{bool }{IsQueryOnly}{}
3104
3105 Accessor function that returns a value indicating if this wxDbTable instance
3106 was created to allow only queries to be performed on the bound columns.  If
3107 this function returns true, then no actions may be performed using this
3108 wxDbTable instance that would modify (insert/delete/update) the table's data.
3109
3110 \membersection{wxDbTable::Open}\label{wxdbtableopen}
3111
3112 \func{bool }{Open}{\param{bool }{checkPrivileges=false}, \param{bool }{checkTableExists=true}}
3113
3114 Every wxDbTable instance must be opened before it can be used.  This function
3115 checks for the existence of the requested table, binds columns, creates required
3116 cursors, (insert/select and update if connection is not wxDB\_QUERY\_ONLY) and
3117 constructs the insert statement that is to be used for inserting data as a new
3118 row in the datasource.
3119
3120 \wxheading{Parameters}
3121
3122 \docparam{checkPrivileges}{Indicates whether the Open() function should check
3123 whether the current connected user has at least SELECT privileges to access the
3124 table to which they are trying to open.  Default is false.}
3125
3126 \docparam{checkTableExists}{Indicates whether the Open() function should check
3127 whether the table exists in the database or not before opening it.  Default is true.}
3128
3129 \wxheading{Remarks}
3130
3131 If the function returns a false value due to the table not existing, a log
3132 entry is recorded for the datasource connection indicating the problem
3133 that was detected when checking for table existence.  Note that it is usually
3134 best for the calling routine to check for the existence of the table and for
3135 sufficient user privileges to access the table in the mode (wxDB\_QUERY\_ONLY or
3136 !wxDB\_QUERY\_ONLY) before trying to open the table for the best possible
3137 explanation as to why a table cannot be opened.
3138
3139 Checking the user's privileges on a table can be quite time consuming during
3140 the open phase.  With most applications, the programmer already knows that the
3141 user has sufficient privileges to access the table, so this check is normally
3142 not required.
3143
3144 For best performance, open the table, and then use the
3145 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} function
3146 to check the users privileges.  Passing a schema to the TablePrivileges()
3147 function can significantly speed up the privileges checks.
3148
3149 \wxheading{See also}
3150
3151 \helpref{wxDb::TableExists}{wxdbtableexists},
3152 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
3153
3154 \membersection{wxDbTable::OrderBy}\label{wxdbtableorderby}
3155
3156 \func{const wxString \&}{OrderBy}{}
3157
3158 \func{void}{OrderBy}{\param{const wxString \&}{OrderBy}}
3159
3160 Accessor function for the private class member wxDbTable::orderBy.  Can be
3161 used as a synonym for
3162 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
3163 (the first form of this function) or
3164 \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}
3165 (the second form of this function).
3166
3167 \wxheading{Parameters}
3168
3169 \docparam{OrderBy}{A comma separated list of column names that indicate the
3170 alphabetized/numeric sorting sequence that the result set is to be returned
3171 in.  If a FROM clause has also been specified, each column name specified in
3172 the ORDER BY clause should be prefaced with the table name to which the column
3173 belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
3174
3175 \wxheading{Return value}
3176
3177 The first form of this function returns the current value of the wxDbTable
3178 member variable ::orderBy.
3179
3180 The second form of the function has no return value.
3181
3182 \wxheading{See also}
3183
3184 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause},
3185 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
3186
3187 \membersection{wxDbTable::Query}\label{wxdbtablequery}
3188
3189 \func{virtual bool }{Query}{\param{bool }{forUpdate=false}, \param{bool }{distinct=false}}
3190
3191 \wxheading{Parameters}
3192
3193 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3194 as they are retrieved.  If the RDBMS is not capable of the FOR UPDATE clause,
3195 this argument is ignored.  See
3196 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3197 additional information regarding this argument.  Default is false.}
3198 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3199 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3200 applies to all columns returned in the result set, not individual columns.
3201 Default is false.}
3202
3203 \wxheading{Remarks}
3204
3205 This function queries records from the datasource based on the three
3206 wxDbTable members: "where", "orderBy", and "from".  Use
3207 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} to filter on
3208 records to be retrieved (e.g. All users with a first name of "JOHN").
3209 Use \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause} to
3210 change the sequence in which records are returned in the result set from
3211 the datasource (e.g. Ordered by LAST\_NAME).  Use
3212 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} to allow outer
3213 joining of the base table (the one being associated with this instance of
3214 wxDbTable) with other tables which share a related field.
3215
3216 After each of these clauses are set/cleared, call wxDbTable::Query() to
3217 fetch the result set from the datasource.
3218
3219 This scheme has an advantage if you have to requery your record set
3220 frequently in that you only have to set your WHERE, ORDER BY, and FROM
3221 clauses once.  Then to refresh the record set, simply call wxDbTable::Query()
3222 as frequently as needed.
3223
3224 Note that repeated calls to wxDbTable::Query() may tax the database
3225 server and make your application sluggish if done too frequently or
3226 unnecessarily.
3227
3228 The base table name is automatically prepended to the base column names in
3229 the event that the FROM clause has been set (is non-null) using
3230 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
3231
3232 The cursor for the result set is positioned {\it before} the first record in
3233 the result set after the query.  To retrieve the first record, call either
3234 \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} (only if backward scrolling
3235 cursors are available) or
3236 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.  Typically, no data from the
3237 result set is returned to the client driver until a request such as
3238 \helpref{wxDbTable::GetNext}{wxdbtablegetnext} is performed, so network
3239 traffic and database load are not overwhelmed transmitting data until the
3240 data is actually requested by the client.  This behavior is solely dependent
3241 on the ODBC driver though, so refer to the ODBC driver's reference material
3242 for information on its behaviors.
3243
3244 Values in the bound columns' memory variables are undefined after executing a
3245 call to this function and remain that way until a row in the result set is
3246 requested to be returned.
3247
3248 The wxDbTable::Query() function is defined as "virtual" so that it may be
3249 overridden for application specific purposes.
3250
3251 \normalbox{Be sure to set the wxDbTable's "where", "orderBy", and "from"
3252 member variables to "" if they are not to be used in the query.  Otherwise,
3253 the results returned may have unexpected results (or no results) due to
3254 improper or incorrect query parameters constructed from the uninitialized
3255 clauses.}
3256
3257 \wxheading{Example}
3258
3259 \begin{verbatim}
3260     // Incomplete code sample
3261     parts->SetWhereClause("DESCRIPTION = 'FOOD'");
3262     parts->SetOrderByClause("EXPIRATION_DATE");
3263     parts->SetFromClause("");
3264     // Query the records based on the where, orderBy and from clauses
3265     // specified above
3266     parts->Query();
3267     // Display all records queried
3268     while(parts->GetNext())
3269         dispPart(parts);  // user defined function
3270 \end{verbatim}
3271
3272 \membersection{wxDbTable::QueryBySqlStmt}\label{wxdbtablequerybysqlstmt}
3273
3274 \func{bool}{QueryBySqlStmt}{\param{const wxString \&}{pSqlStmt}}
3275
3276 Performs a query against the datasource by accepting and passing verbatim the
3277 SQL SELECT statement passed to the function.
3278
3279 \wxheading{Parameters}
3280
3281 \docparam{pSqlStmt}{Pointer to the SQL SELECT statement to be executed.}
3282
3283 \wxheading{Remarks}
3284
3285 This is the most powerful form of the query functions available.  This member
3286 function allows a programmer to write their own custom SQL SELECT statement
3287 for requesting data from the datasource.  This gives the programmer access
3288 to the full power of SQL for performing operations such as scalar functions,
3289 aggregate functions, table joins, and sub-queries, as well as datasource
3290 specific function calls.
3291
3292 The requirements of the SELECT statement are the following:
3293
3294 \begin{enumerate}
3295 \item Must return the correct number of columns.  In the derived
3296 wxDbTable constructor, it is specified how many columns are in
3297 the wxDbTable object. The SELECT statement must return exactly
3298 that many columns.
3299 \item The columns must be returned in the same sequence as specified
3300 when defining the bounds columns using wxDbTable::SetColDefs(),
3301 and the columns returned must be of the proper data type.  For
3302 example, if column 3 is defined in the wxDbTable bound column
3303 definitions to be a float, the SELECT statement must return a
3304 float for column 3 (e.g. PRICE * 1.10 to increase the price by
3305 10%).
3306 \item The ROWID can be included in your SELECT statement as the {\bf last}
3307 column selected, if the datasource supports it.  Use
3308 wxDbTable::CanUpdByROWID() to determine if the ROWID can be
3309 selected from the datasource.  If it can, much better
3310 performance can be achieved on updates and deletes by including
3311 the ROWID in the SELECT statement.
3312 \end{enumerate}
3313
3314 Even though data can be selected from multiple tables (joins) in your select
3315 statement, only the base table associated with this wxDbTable object
3316 is automatically updated through the ODBC class library.  Data from multiple
3317 tables can be selected for display purposes however.  Include columns in
3318 the wxDbTable object and mark them as non-updateable (See
3319 \helpref{wxDbColDef}{wxdbcoldef} for details).  This way columns can be
3320 selected and displayed from other tables, but only the base table will be
3321 updated automatically when performed through the
3322 \helpref{wxDbTable::Update}{wxdbtableupdate} function after using this type of
3323 query.  To update tables other than the base table, use the
3324 \helpref{wxDbTable::Update}{wxdbtableupdate} function passing a SQL statement.
3325
3326 After this function has been called, the cursor is positioned before the
3327 first record in the record set.  To retrieve the first record, call
3328 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3329 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3330
3331 \wxheading{Example}
3332
3333 \begin{verbatim}
3334     // Incomplete code samples
3335          wxString sqlStmt;
3336     sqlStmt = "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
3337                AND CONTAINER = 12";
3338     // Query the records using the SQL SELECT statement above
3339     parts->QueryBySqlStmt(sqlStmt);
3340     // Display all records queried
3341     while(parts->GetNext())
3342         dispPart(&parts);
3343
3344     Example SQL statements
3345     ----------------------
3346
3347     // Table Join returning 3 columns
3348     SELECT part_no, part_desc, sd_name
3349         from parts, storage_devices
3350         where parts.storage_device_id =
3351               storage_devices.storage_device_id
3352
3353     // Aggregate function returning total number of
3354     // parts in container 99
3355     SELECT count(*) from PARTS where container = 99
3356
3357     // Order by clause; ROWID, scalar function
3358     SELECT part_no, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
3359         from parts
3360         where warehouse = 10
3361         order by part_no desc           // descending order
3362
3363     // Subquery
3364     SELECT * from parts
3365         where container in (select container
3366         from storage_devices
3367             where device_id = 12)
3368 \end{verbatim}
3369
3370 \membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
3371
3372 \func{virtual bool }{QueryMatching}{\param{bool }{forUpdate=false},
3373 \param{bool }{distinct=false}}
3374
3375 QueryMatching allows querying of records from the table associated with
3376 the wxDbTable object by matching "columns" to values.
3377
3378 For example: To query the datasource for the row with a PART\_NUMBER column
3379 value of "32", clear all column variables of the wxDbTable object, set the
3380 PartNumber variable that is bound to the PART\_NUMBER column in the wxDbTable
3381 object to "32", and then call wxDbTable::QueryMatching().
3382
3383 \wxheading{Parameters}
3384
3385 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3386 as they are queried (SELECT ... FOR UPDATE).  If the RDBMS is not capable of
3387 the FOR UPDATE clause, this argument is ignored.  See
3388 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3389 additional information regarding this argument.  Default is false.}
3390 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3391 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3392 applies to all columns returned in the result set, not individual columns.
3393 Default is false.}
3394
3395 \wxheading{Remarks}
3396
3397 The SQL WHERE clause is built by the ODBC class library based on all
3398 non-zero/non-NULL columns in your wxDbTable object.  Matches can be on one,
3399 many or all of the wxDbTable's columns.  The base table name is prepended
3400 to the column names in the event that the wxDbTable's FROM clause is non-null.
3401
3402 This function cannot be used to perform queries which will check for
3403 columns that are 0 or NULL, as the automatically constructed WHERE clause
3404 only will contain comparisons on column member variables that are
3405 non-zero/non-NULL.
3406
3407 The primary difference between this function and \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields}
3408 is that this function can query on any column(s) in the wxDbTable object.
3409 Note however that this may not always be very efficient.  Searching on
3410 non-indexed columns will always require a full table scan.
3411
3412 The cursor is positioned before the first record in the record set after
3413 the query is performed.  To retrieve the first record, the program must call
3414 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3415 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3416
3417 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3418 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3419 this function.
3420
3421 \wxheading{Example}
3422
3423 \begin{verbatim}
3424     // Incomplete code sample
3425     parts->ClearMemberVars();           // Set all columns to zero
3426     wxStrcpy(parts->PartNumber,"32");   // Set columns to query on
3427     parts->OnHold = true;
3428     parts->QueryMatching();             // Query
3429     // Display all records queried
3430     while(parts->GetNext())
3431         dispPart(parts);  // Some application defined function
3432 \end{verbatim}
3433
3434 \membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
3435
3436 \func{bool }{QueryOnKeyFields}{\param{bool }{forUpdate=false},
3437 \param{bool }{distinct=false}}
3438
3439 QueryOnKeyFields provides an easy mechanism to query records in the table
3440 associated with the wxDbTable object by the primary index column(s).  Simply
3441 assign the primary index column(s) values and then call this member function
3442 to retrieve the record.
3443
3444 Note that since primary indexes are always unique, this function implicitly
3445 always returns a single record from the database. The base table name is
3446 prepended to the column names in the event that the wxDbTable's FROM clause
3447 is non-null.
3448
3449 \wxheading{Parameters}
3450
3451 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3452 as they are queried (SELECT ... FOR UPDATE).  If the RDBMS is not capable of
3453 the FOR UPDATE clause, this argument is ignored.  See
3454 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3455 additional information regarding this argument.  Default is false.}
3456 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3457 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3458 applies to all columns returned in the result set, not individual columns.
3459 Default is false.}
3460
3461 \wxheading{Remarks}
3462
3463 The cursor is positioned before the first record in the record set after
3464 the query is performed.  To retrieve the first record, the program must call
3465 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3466 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3467
3468 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3469 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3470 this function.
3471
3472 \wxheading{Example}
3473
3474 \begin{verbatim}
3475     // Incomplete code sample
3476     wxStrcpy(parts->PartNumber, "32");
3477     parts->QueryOnKeyFields();
3478     // Display all records queried
3479     while(parts->GetNext())
3480         dispPart(parts);  // Some application defined function
3481 \end{verbatim}
3482
3483 \membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
3484
3485 \func{bool}{Refresh}{\void}
3486
3487 This function re-reads the bound columns into the memory variables, setting
3488 them to the current values stored on the disk.
3489
3490 The cursor position and result set are unaffected by calls to this function.
3491 (The one exception is in the case where the record to be refreshed has been
3492 deleted by some other user or transaction since it was originally retrieved
3493 as part of the result set.  For most datasources, the default behavior in
3494 this situation is to return the value that was originally queried for the
3495 result set, even though it has been deleted from the database.  But this is
3496 datasource dependent, and should be tested before relying on this behavior.)
3497
3498 \wxheading{Remarks}
3499
3500 This routine is only guaranteed to work if the table has a unique primary
3501 index defined for it.  Otherwise, more than one record may be fetched and
3502 there is no guarantee that the correct record will be refreshed.  The
3503 table's columns are refreshed to reflect the current data in the database.
3504
3505 \membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
3506
3507 \func{void}{SetColDefs}{\param{UWORD }{index}, \param{const wxString \&}{fieldName},
3508 \param{int }{dataType}, \param{void *}{pData}, \param{SWORD }{cType},
3509 \param{int }{size}, \param{bool }{keyField = false}, \param{bool }{upd = true},
3510 \param{bool }{insAllow = true}, \param{bool }{derivedCol = false}}
3511
3512 \func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{UWORD }{numCols}}
3513
3514 \wxheading{Parameters}
3515
3516 \docparam{index}{Column number (0 to n-1, where n is the number of columns
3517 specified as being defined for this wxDbTable instance when the
3518 wxDbTable constructor was called.}
3519 \docparam{fieldName}{Column name from the associated data table.}
3520 \docparam{dataType}{Logical data type.  Valid logical types include:}
3521
3522 \begin{verbatim}
3523     DB_DATA_TYPE_VARCHAR        : strings
3524     DB_DATA_TYPE_INTEGER        : non-floating point numbers
3525     DB_DATA_TYPE_FLOAT          : floating point numbers
3526     DB_DATA_TYPE_DATE           : dates
3527 \end{verbatim}
3528
3529 \docparam{pData}{Pointer to the data object that will hold the column's
3530 value when a row of data is returned from the datasource.}
3531 \docparam{cType}{SQL C Type.  This defines the data type that the SQL
3532 representation of the data is converted to to be stored in {\it pData}.
3533 Other valid types are available also, but these are the most common ones:}
3534
3535 \begin{verbatim}
3536     SQL_C_CHAR      // strings
3537     SQL_C_LONG
3538     SQL_C_ULONG
3539     SQL_C_SHORT
3540     SQL_C_USHORT
3541     SQL_C_FLOAT
3542     SQL_C_DOUBLE
3543     SQL_C_NUMERIC
3544     SQL_C_TIMESTAMP
3545
3546     SQL_C_BOOLEAN   // defined in db.h
3547     SQL_C_ENUM      // defined in db.h
3548 \end{verbatim}
3549
3550 \docparam{size}{Maximum size in bytes of the {\it pData} object.}
3551 \docparam{keyField}{{\it OPTIONAL}.  Indicates if this column is part of the
3552 primary index.  Default is false.}
3553 \docparam{upd}{{\it OPTIONAL}.  Are updates allowed on this column?
3554 Default is true.}
3555 \docparam{insAllow}{{\it OPTIONAL}.  Inserts allowed on this column?
3556 Default is true.}
3557 \docparam{derivedCol}{{\it OPTIONAL}.  Is this a derived column (non-base
3558 table column for query only)?  Default is false.}
3559
3560 \docparam{colInfs}{Pointer to an array of wxDbColInf instances which contains
3561 all the information necessary to create {\it numCols} column definitions.}
3562 \docparam{numCols}{Number of elements of wxDbColInf type that are pointed
3563 to by {\it colInfs}, which are to have column definitions created from them.}
3564
3565 \wxheading{Remarks}
3566
3567 If {\it pData} is to hold a string of characters, be sure to include enough
3568 space for the NULL terminator in pData and in the byte count of {\it size}.
3569
3570 Both forms of this function provide a shortcut for defining the columns in
3571 your wxDbTable object.  Use this function in any derived wxDbTable
3572 constructor when describing the column/columns in the wxDbTable object.
3573
3574 The second form of this function is primarily used when the
3575 \helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
3576 datasource for the column definitions, so that the column definitions are
3577 already stored in wxDbColInf form.  One example use of using
3578 \helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
3579 a data table existed in one datasource, and the table's column definitions
3580 were to be copied over to another datasource or table.
3581
3582 \wxheading{Example}
3583
3584 \begin{verbatim}
3585     // Long way not using this function
3586     wxStrcpy(colDefs[0].ColName, "PART_NO");
3587     colDefs[0].DbDataType   = DB_DATA_TYPE_VARCHAR;
3588     colDefs[0].PtrDataObj   = PartNumber;
3589     colDefs[0].SqlCtype     = SQL_C_CHAR;
3590     colDefs[0].SzDataObj    = PART_NUMBER_LEN;
3591     colDefs[0].KeyField     = true;
3592     colDefs[0].Updateable   = false;
3593     colDefs[0].InsertAllowed= true;
3594     colDefs[0].DerivedCol   = false;
3595
3596     // Shortcut using this function
3597     SetColDefs(0, "PART_NUMBER", DB_DATA_TYPE_VARCHAR, PartNumber,
3598                SQL_C_CHAR, PART_NUMBER_LEN, true, false,true,false);
3599 \end{verbatim}
3600
3601 \membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
3602
3603 \func{bool}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB\_DEFAULT\_CURSOR}}
3604
3605 \wxheading{Parameters}
3606
3607 \docparam{hstmtActivate}{{\it OPTIONAL}.  Pointer to the cursor that is to
3608 become the current cursor.  Passing no cursor handle will reset the cursor
3609 back to the wxDbTable's default (original) cursor that was created when the
3610 wxDbTable instance was first created.  Default is wxDB\_DEFAULT\_CURSOR.}
3611
3612 \wxheading{Remarks}
3613
3614 When swapping between cursors, the member variables of the wxDbTable object
3615 are automatically refreshed with the column values of the row that the
3616 current cursor is positioned at (if any).  If the cursor is not positioned,
3617 then the data in member variables is undefined.
3618
3619 The only way to return back to the cursor that was in use before this
3620 function was called is to programmatically determine the current cursor's HSTMT
3621 {\bf BEFORE} calling this function using \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor}
3622 and saving a pointer to that cursor.
3623
3624 \wxheading{See also}
3625
3626 \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor},
3627 \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor},
3628 \helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}
3629
3630 \membersection{wxDbTable::SetFromClause}\label{wxdbtablesetfromclause}
3631
3632 \func{void}{SetFromClause}{\param{const wxString \&}{From}}
3633
3634 Accessor function for setting the private class member wxDbTable::from
3635 that indicates what other tables should be outer joined with the wxDbTable's
3636 base table for access to the columns in those other tables.
3637
3638 Synonym to this function is one form of \helpref{wxDbTable::From}{wxdbtablefrom}
3639
3640 \wxheading{Parameters}
3641
3642 \docparam{From}{A comma separated list of table names that are to be outer
3643 joined with the base table's columns so that the joined table's columns
3644 may be returned in the result set or used as a portion of a comparison with
3645 the base table's columns.  NOTE that the base tables name must NOT be included
3646 in the FROM clause, as it is automatically included by the wxDbTable class
3647 in constructing query statements.}
3648
3649 \wxheading{Remarks}
3650
3651 Used by the \helpref{wxDbTable::Query}{wxdbtablequery} and
3652 \helpref{wxDbTable::Count}{wxdbtablecount} member functions to allow outer
3653 joining of records from multiple tables.
3654
3655 Do {\bf not} include the keyword "FROM" when setting the FROM clause.
3656
3657 If using the FROM clause when performing a query, be certain to include in
3658 the corresponding WHERE clause a comparison of a column from either the base
3659 table or one of the other joined tables to each other joined table to ensure
3660 the datasource knows on which column values the tables should be joined on.
3661
3662 \wxheading{Example}
3663
3664 \begin{verbatim}
3665     ...
3666     // Base table is the "LOCATION" table, and it is being
3667     // outer joined to the "PART" table via the the field "PART_NUMBER"
3668     // that can be related between the two tables.
3669     location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
3670     location->SetFromClause("PART");
3671     ...
3672 \end{verbatim}
3673
3674 \wxheading{See also}
3675
3676 \helpref{wxDbTable::From}{wxdbtablefrom},
3677 \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
3678
3679 \membersection{wxDbTable::SetColNull}\label{wxdbtablesetcolnull}
3680
3681 \func{bool}{SetColNull}{\param{UWORD }{colNo}, \param{bool }{set=true}}
3682
3683 \func{bool}{SetColNull}{\param{const wxString \&}{colName},
3684 \param{bool }{set=true}}
3685
3686 Both forms of this function allow a member variable representing a column
3687 in the table associated with this wxDbTable object to be set to NULL.
3688
3689 The first form allows the column to be set by the index into the column
3690 definitions used to create the wxDbTable instance, while the second allows
3691 the actual column name to be specified.
3692
3693 \wxheading{Parameters}
3694
3695 \docparam{colNo}{Index into the column definitions used when first defining
3696 this wxDbTable object.}
3697 \docparam{colName}{Actual data table column name that is to be set to NULL.}
3698 \docparam{set}{Whether the column is set to NULL or not.  Passing true sets
3699 the column to NULL, passing false sets the column to be non-NULL.  Default is
3700 true.}
3701
3702 \wxheading{Remarks}
3703
3704 No database updates are done by this function.  It only operates on the
3705 member variables in memory.  Use and insert or update function to store this
3706 value to disk.
3707
3708 \membersection{wxDbTable::SetOrderByClause}\label{wxdbtablesetorderbyclause}
3709
3710 \func{void}{SetOrderByClause}{\param{const wxString \&}{OrderBy}}
3711
3712 Accessor function for setting the private class member wxDbTable::orderBy
3713 which determines sequence/ordering of the rows returned in the result set
3714 of a query.
3715
3716 A synonym to this function is one form of the function \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
3717
3718 \wxheading{Parameters}
3719
3720 \docparam{OrderBy}{A comma separated list of column names that indicate the
3721 alphabetized sorting sequence that the result set is to be returned in.  If
3722 a FROM clause has also been specified, each column name specified in the
3723 ORDER BY clause should be prefaced with the table name to which the column
3724 belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
3725
3726 \wxheading{Remarks}
3727
3728 Do {\bf not} include the keywords "ORDER BY" when setting the ORDER BY clause.
3729
3730 \wxheading{Example}
3731
3732 \begin{verbatim}
3733     ...
3734     parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
3735     ...
3736
3737     ...
3738     location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
3739     ...
3740 \end{verbatim}
3741
3742 \wxheading{See also}
3743
3744 \helpref{wxDbTable::OrderBy}{wxdbtableorderby},
3745 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
3746
3747 \membersection{wxDbTable::SetQueryTimeout}\label{wxdbtablesetquerytimeout}
3748
3749 \func{bool}{SetQueryTimeout}{\param{UDWORD }{nSeconds}}
3750
3751 Allows a time period to be set as the timeout period for queries.
3752
3753 \wxheading{Parameters}
3754
3755 \docparam{nSeconds}{The number of seconds to wait for the query to complete
3756 before timing out.}
3757
3758 \wxheading{Remarks}
3759
3760 Neither Oracle or Access support this function as of yet.  Other databases
3761 should be evaluated for support before depending on this function working
3762 correctly.
3763
3764 \membersection{wxDbTable::SetWhereClause}\label{wxdbtablesetwhereclause}
3765
3766 \func{void}{SetWhereClause}{\param{const wxString \&}{Where}}
3767
3768 Accessor function for setting the private class member wxDbTable::where
3769 that determines which rows are returned in the result set by the datasource.
3770
3771 A synonym to this function is one form of the function \helpref{wxDbTable::Where}{wxdbtablewhere}
3772
3773 \wxheading{Parameters}
3774
3775 \docparam{Where}{SQL "where" clause.  This clause can contain any SQL language
3776 that is legal in standard where clauses.  If a FROM clause has also been
3777 specified, each column name specified in the ORDER BY clause should be
3778 prefaced with the table name to which the column belongs using DOT notation
3779 (TABLE\_NAME.COLUMN\_NAME).}
3780
3781 \wxheading{Remarks}
3782
3783 Do {\bf not} include the keywords "WHERE" when setting the WHERE clause.
3784
3785 \wxheading{Example}
3786
3787 \begin{verbatim}
3788     ...
3789     // Simple where clause
3790     parts->SetWhereClause("PART_NUMBER = '32'");
3791     ...
3792     // Any comparison operators
3793     parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER%'");
3794     ...
3795     // Multiple comparisons, including a function call
3796     parts->Where("QTY > 0 AND {fn UCASE(PART_DESCRIP)} LIKE '%DRILL%'");
3797     ...
3798     // Using parameters and multiple logical combinations
3799     parts->Where("((QTY > 10) OR (ON_ORDER > 0)) AND ON_HOLD = 0");
3800     ...
3801     // This query uses an outer join (requiring a FROM clause also)
3802     // that joins the PART and LOCATION table on he common field
3803     // PART_NUMBER.
3804     parts->Where("PART.ON_HOLD = 0 AND \
3805                   PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
3806                   LOCATION.PART_NUMBER > 0");
3807 \end{verbatim}
3808
3809 \wxheading{See also}
3810
3811 \helpref{wxDbTable::Where}{wxdbtablewhere},
3812 \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
3813
3814 \membersection{wxDbTable::Update}\label{wxdbtableupdate}
3815
3816 \func{bool }{Update}{\void}
3817
3818 \func{bool }{Update}{\param{const wxString \&}{pSqlStmt}}
3819
3820 The first form of this function will update the row that the current cursor
3821 is currently positioned at with the values in the memory variables that
3822 are bound to the columns.  The actual SQL statement to perform the update
3823 is automatically created by the ODBC class, and then executed.
3824
3825 The second form of the function allows full access through SQL statements for
3826 updating records in the database.  Write any valid SQL UPDATE statement and
3827 submit it to this function for execution.  Sophisticated updates can be
3828 performed using the full power of the SQL dialect. The full SQL statement
3829 must have  the exact syntax required by the driver/datasource for performing
3830 the update.  This usually is in the form of:
3831
3832 \begin{verbatim}
3833     UPDATE tablename SET col1=X, col2=Y, ... where ...
3834 \end{verbatim}
3835
3836 \wxheading{Parameters}
3837
3838 \docparam{pSqlStmt}{Pointer to SQL UPDATE statement to be executed.}
3839
3840 \wxheading{Remarks}
3841
3842 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3843 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3844 this function to commit or rollback the update.
3845
3846 \wxheading{Example}
3847
3848 \begin{verbatim}
3849          wxString sqlStmt;
3850     sqlStmt = "update PART set QTY = 0 where PART_NUMBER = '32'";
3851 \end{verbatim}
3852
3853 \membersection{wxDbTable::UpdateWhere}\label{wxdbtableupdatewhere}
3854
3855 \func{bool}{UpdateWhere}{\param{const wxString \&}{pWhereClause}}
3856
3857 Performs updates to the base table of the wxDbTable object, updating only the
3858 rows which match the criteria specified in the {\it pWhereClause}.
3859
3860 All columns that are bound to member variables for this wxDbTable instance
3861 that were defined with the "updateable" parameter set to true will be updated
3862 with the information currently held in the memory variable.
3863
3864 \wxheading{Parameters}
3865
3866 \docparam{pWhereClause}{Pointer to a valid SQL WHERE clause.  Do not
3867 include the keyword 'WHERE'.}
3868
3869 \wxheading{Remarks}
3870
3871 Care should be used when updating columns that are part of indexes with
3872 this function so as not to violate an unique key constraints.
3873
3874 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3875 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3876 this function to commit or rollback the update(s).
3877
3878 \membersection{wxDbTable::Where}\label{wxdbtablewhere}
3879
3880 \func{const wxString \&}{Where}{}
3881
3882 \func{void}{Where}{\param{const wxString\& }{Where}}
3883
3884 Accessor function for the private class member wxDbTable::where.  Can be used
3885 as a synonym for \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
3886 (the first form of this function) to return the current where clause or
3887 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} (the second form
3888 of this function) to set the where clause for this table instance.
3889
3890 \wxheading{Parameters}
3891
3892 \docparam{Where}{A valid SQL WHERE clause.  Do not include the keyword 'WHERE'.}
3893
3894 \wxheading{Return value}
3895
3896 The first form of this function returns the current value of the wxDbTable
3897 member variable ::where.
3898
3899 The second form of the function has no return value, as it will always set
3900 the where clause successfully.
3901
3902 \wxheading{See also}
3903
3904 \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause},
3905 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3906
3907 \membersection{wxDbTable::operator $++$}\label{wxdbtableplusplus}
3908
3909 \func{bool}{operator $++$}{\void}
3910
3911 Synonym for \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
3912
3913 \wxheading{See also}
3914
3915 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
3916
3917 \membersection{wxDbTable::operator $--$}\label{wxdbtableminusminus}
3918
3919 \func{bool}{operator $--$}{\void}
3920
3921 Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
3922
3923 \wxheading{See also}
3924
3925 \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
3926
3927 \section{\class{wxDbTableInf}}\label{wxdbtableinf}
3928
3929 \begin{verbatim}
3930     tableName[0]    = 0;
3931     tableType[0]    = 0;
3932     tableRemarks[0] = 0;
3933     numCols         = 0;
3934     pColInf         = NULL;
3935 \end{verbatim}
3936
3937 Currently only used by \helpref{wxDb::GetCatalog}{wxdbgetcatalog} internally
3938 and \helpref{wxDbInf}{wxdbinf} class, but may be used in future releases for
3939 user functions.  Contains information describing the table (Name, type, etc).
3940 A pointer to a wxDbColInf array instance is included so a program can create a
3941 \helpref{wxDbColInf}{wxdbcolinf} array instance (using
3942 \helpref{wxDb::GetColumns}{wxdbgetcolumns})
3943 to maintain all information about the columns of a table in one memory
3944 structure.
3945
3946 Eventually, accessor functions will be added for this class
3947
3948 See the \helpref{database classes overview}{odbcoverview} for
3949 an introduction to using the ODBC classes.
3950
3951 \membersection{wxDbTableInf::Initialize}\label{wxdbtableinfinitialize}
3952
3953 Simply initializes all member variables to a cleared state.  Called by
3954 the constructor automatically.
3955
3956 \section{\class{wxDbGridColInfo}}\label{wxdbgridcolinfo}
3957
3958 This class is used  to define columns to be shown, names of the columns,
3959 order and type of data, when using \helpref{wxdbGridTableBase}{wxdbgridtablebase} to display
3960 a Table or query in a \helpref{wxGrid}{wxgrid}
3961
3962 See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} for
3963 an introduction to using the wxDbGrid classes.
3964
3965 \wxheading{Include files}
3966
3967 <wx/dbgrid.h>
3968
3969 \latexignore{\rtfignore{\wxheading{Members}}}
3970
3971 \membersection{wxDbGridColInfo::wxDbGridColInfo}\label{wxdbgridcolinfoctor}
3972
3973 \func{}{wxDbGridColInfo}{\param{int }{colNo}, \param{wxString }{type},
3974   \param{wxString }{title}, \param{wxDbGridColInfo *}{next}}
3975
3976 Default constructor. See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
3977 see two different ways for adding columns.
3978
3979
3980 \wxheading{Parameters}
3981
3982 \docparam{colNo}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
3983 \docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
3984  use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
3985 \docparam{title}{The column label to be used in the grid display}
3986 \docparam{next}{A pointer to the next wxDbGridColInfo structure if using one-step
3987 construction, NULL  terminates the list. Use Null also if using two step construction.}
3988 See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
3989 see two different ways for adding columns.
3990
3991 \membersection{wxDbGridColInfo::\destruct{wxDbGridColInfo}}
3992
3993 \func{}{\destruct{wxDbGridColInfo}}{}
3994
3995 Destructor.
3996
3997 \membersection{wxDbGridColInfo::AddColInfo}\label{wxdbgridcolinfoaddcolinfo}
3998
3999 \func{void}{AddColInfo}{\param{int }{colNo},
4000 \param{wxString }{type}, \param{wxString }{title}}
4001
4002 Use this member function for adding columns. See the database
4003 grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
4004 see two different ways for adding columns.
4005
4006 It is important to note that this class is merely a specifier to the \helpref{wxDbGridTableBase}{wxdbgridtablebase}
4007 constructor. Changes made to this datatype after the \helpref{wxDbGridTableBase}{wxdbgridtablebase} is called will
4008 not have any effect.
4009
4010 \wxheading{Parameters}
4011 \docparam{colNo}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
4012 \docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
4013  use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
4014 \docparam{title}{The column label to be used in the grid display}
4015
4016 \wxheading{Remarks}
4017
4018 As wxDbTable must be defined with to have columns which match those  to by a wxDbGridColInfo
4019 info structure as this is the structure which informs the grid of how you want to display your
4020 \helpref{wxDbTable}{wxdbtable}. If no datatype conversion or the referenced column number does not exist the
4021 the behavior is undefined.
4022
4023 See the example at \helpref{wxDbGridColInfo::wxDbGridColInfo}{wxdbgridcolinfoctor}.
4024
4025 \section{\class{wxDbGridTableBase}}\label{wxdbgridtablebase}
4026
4027 You can view a database table in a grid using this class.
4028
4029 If you are deriving your own wxDbTable subclass for your table , then you may consider
4030 overriding GetCol() and SetCol() to provide calculated fields. This does work but care should
4031 be taken when using wxDbGridTableBase in this way.
4032
4033 The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable
4034 object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable
4035 when an new on is assigned or wxGridTableBase's destructor is called.
4036 However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true);
4037 is  an error. If you need to requery an table object the preferred way is
4038 that the client keeps ownership.
4039
4040 \wxheading{Derived From}
4041
4042 \helpref{wxGridTableBase}{wxgridtablebase}
4043
4044 \wxheading{Include files}
4045
4046 <wx/dbgrid.h>
4047
4048
4049 \wxheading{Example}
4050
4051 \begin{verbatim}
4052         // First step, let's define wxDbTable
4053         int numColumns = 2;
4054         wxDbTable *table = new wxDbTable (db, tblName, numColumns);
4055         int int_var;
4056         wxChar string_name[255];
4057         table->SetColDef (0, "column 0", DB_DATA_TYPE_INTEGER, &int_var,
4058                         SQL_C_LONG, sizeof(int_var), true);
4059         table->SetColDef (1, "column 1", DB_DATA_TYPE_VARCHAR, &string_name,
4060                         SQL_C_LONG, sizeof(string_name), false);
4061
4062     // now let's define columns in the grid
4063
4064     // first way to do it
4065     wxDbGridColInfo *columns;
4066     columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column",
4067               new wxDbGridColInfo(1, wxGRID_VALUE_STRING, "second column",
4068               NULL);
4069
4070     // second way to do it
4071     wxDbGridColInfo *columns;
4072     // first column is special
4073     columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column", NULL);
4074     // all the rest
4075     columns->AddColInfo (1, wxGRID_VALUE_STRING, "second column");
4076
4077     // second way may be better when columns are not known at compile time
4078
4079     // now, let's open the table and make a Query()
4080     table->Open();
4081     // this step is very important
4082     table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
4083     // in the grid we will see only the rows of the result query
4084     m_dbTable->Query();
4085
4086     wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, true);
4087     delete columns;  // not needed anymore
4088     wxGrid *grid = new wxGrid ( ... );
4089     grid->SetTable(dbgrid, true);
4090     grid->Fit();
4091 \end{verbatim}
4092
4093
4094 \wxheading{Include files}
4095
4096 <wx/dbgrid.h>
4097
4098 \wxheading{Helper classes and data structures}
4099
4100 \membersection{wxDbGridTableBase::wxDbGridTableBase}\label{wxdbgridtablebaseconstr}
4101
4102 \func{}{wxDbGridTableBase}{\param{wxDbTable *}{tab}, \param{wxDbGridColInfo *}{ColInfo},
4103   \param{int }{count = wxUSE\_QUERY}, \param{bool }{takeOwnership = true}}
4104
4105 Constructor.
4106
4107 \wxheading{Parameters}
4108
4109 \docparam{tab}{ The database table you want to display. Must be opened and queried before display the grid.
4110 See the example \helpref{above}{wxdbgridtablebase}.}
4111 \docparam{ColInfo}{ Columns titles, and other values. See \helpref{wxDbGridColInfo}{wxdbgridcolinfo}.}
4112 \docparam{count}{You can use a query result set (wxUSE\_QUERY, to use wxDbTable::Count(wxDbTable::Count()
4113  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 }
4114
4115 \docparam{takeOwnership}{ If true, this class deletes wxDbTable when it stops
4116 referring to it, if false application must
4117 take care of deleting it.  }
4118
4119 \membersection{wxDbGridTableBase::ValidateRow}\label{wxdbgridtablebasevalidate}
4120
4121 \func{void}{ValidateRow}{\param{int }{row}}
4122
4123 It ensures that the row data is fetched from the database, and it the wxDbTable local buffer,
4124 the row number passed should be the grid row.
4125
4126 \wxheading{Parameters}
4127
4128 \docparam{row}{ Row where validation must be done. }
4129
4130 \membersection{wxDbGridTableBase::UpdateRow}\label{wxdbgridtablebaseupdaterow}
4131
4132 \func{bool}{UpdateRow}{\param{int }{row}}
4133
4134 If row has changed it forces that row to be written back to the database, however support
4135 for detecting whether insert/update is required is currently not in wxDbTable, so this
4136 function is currently unsupported.
4137
4138 \wxheading{Parameters}
4139
4140 \docparam{row}{ Row you want to update. }
4141
4142 \membersection{wxDbGridTableBase::AssignDbTable}\label{wxdbgridtablebaseassigndbtable}
4143
4144 \func{bool}{AssignDbTable}{\param{wxDbTable *}{tab},\param{int }{count = wxUSE\_QUERY},
4145 \param{bool }{takeOwnership = true}}
4146
4147 Resets the grid for using with a new database table, but using the same columns definition.
4148 This can be useful when re-querying the database and want to see the changes.
4149
4150 \wxheading{Parameters}
4151
4152 \docparam{tab}{ Database table you want to assign to the grid. }
4153 \docparam{count}{ Number of rows you want to show or wxUSE\_QUERY for using a query. }
4154 \docparam{takeOwnership}{ If false, user must take care of deleting tab after deleting
4155 the wxDbGridTableBase. If true, deletion is made by destructor class. }
4156