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 NOTE: To retrieve data into an opened table, the of the table must be bound
3121 to the variables in the program via call(s) to
3122 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} before calling Open().
3123
3124 See the \helpref{database classes overview}{odbcoverview} for
3125 an introduction to using the ODBC classes.
3126
3127 \wxheading{Parameters}
3128
3129 \docparam{checkPrivileges}{Indicates whether the Open() function should check
3130 whether the current connected user has at least SELECT privileges to access the
3131 table to which they are trying to open.  Default is false.}
3132
3133 \docparam{checkTableExists}{Indicates whether the Open() function should check
3134 whether the table exists in the database or not before opening it.  Default is true.}
3135
3136 \wxheading{Remarks}
3137
3138 If the function returns a false value due to the table not existing, a log
3139 entry is recorded for the datasource connection indicating the problem
3140 that was detected when checking for table existence.  Note that it is usually
3141 best for the calling routine to check for the existence of the table and for
3142 sufficient user privileges to access the table in the mode (wxDB\_QUERY\_ONLY or
3143 !wxDB\_QUERY\_ONLY) before trying to open the table for the best possible
3144 explanation as to why a table cannot be opened.
3145
3146 Checking the user's privileges on a table can be quite time consuming during
3147 the open phase.  With most applications, the programmer already knows that the
3148 user has sufficient privileges to access the table, so this check is normally
3149 not required.
3150
3151 For best performance, open the table, and then use the
3152 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} function
3153 to check the users privileges.  Passing a schema to the TablePrivileges()
3154 function can significantly speed up the privileges checks.
3155
3156 \wxheading{See also}
3157
3158 \helpref{wxDb::TableExists}{wxdbtableexists},
3159 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
3160 \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
3161
3162 \membersection{wxDbTable::OrderBy}\label{wxdbtableorderby}
3163
3164 \func{const wxString \&}{OrderBy}{}
3165
3166 \func{void}{OrderBy}{\param{const wxString \&}{OrderBy}}
3167
3168 Accessor function for the private class member wxDbTable::orderBy.  Can be
3169 used as a synonym for
3170 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
3171 (the first form of this function) or
3172 \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}
3173 (the second form of this function).
3174
3175 \wxheading{Parameters}
3176
3177 \docparam{OrderBy}{A comma separated list of column names that indicate the
3178 alphabetized/numeric sorting sequence that the result set is to be returned
3179 in.  If a FROM clause has also been specified, each column name specified in
3180 the ORDER BY clause should be prefaced with the table name to which the column
3181 belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
3182
3183 \wxheading{Return value}
3184
3185 The first form of this function returns the current value of the wxDbTable
3186 member variable ::orderBy.
3187
3188 The second form of the function has no return value.
3189
3190 \wxheading{See also}
3191
3192 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause},
3193 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
3194
3195 \membersection{wxDbTable::Query}\label{wxdbtablequery}
3196
3197 \func{virtual bool }{Query}{\param{bool }{forUpdate=false}, \param{bool }{distinct=false}}
3198
3199 \wxheading{Parameters}
3200
3201 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3202 as they are retrieved.  If the RDBMS is not capable of the FOR UPDATE clause,
3203 this argument is ignored.  See
3204 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3205 additional information regarding this argument.  Default is false.}
3206 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3207 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3208 applies to all columns returned in the result set, not individual columns.
3209 Default is false.}
3210
3211 \wxheading{Remarks}
3212
3213 This function queries records from the datasource based on the three
3214 wxDbTable members: "where", "orderBy", and "from".  Use
3215 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} to filter on
3216 records to be retrieved (e.g. All users with a first name of "JOHN").
3217 Use \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause} to
3218 change the sequence in which records are returned in the result set from
3219 the datasource (e.g. Ordered by LAST\_NAME).  Use
3220 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} to allow outer
3221 joining of the base table (the one being associated with this instance of
3222 wxDbTable) with other tables which share a related field.
3223
3224 After each of these clauses are set/cleared, call wxDbTable::Query() to
3225 fetch the result set from the datasource.
3226
3227 This scheme has an advantage if you have to requery your record set
3228 frequently in that you only have to set your WHERE, ORDER BY, and FROM
3229 clauses once.  Then to refresh the record set, simply call wxDbTable::Query()
3230 as frequently as needed.
3231
3232 Note that repeated calls to wxDbTable::Query() may tax the database
3233 server and make your application sluggish if done too frequently or
3234 unnecessarily.
3235
3236 The base table name is automatically prepended to the base column names in
3237 the event that the FROM clause has been set (is non-null) using
3238 \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
3239
3240 The cursor for the result set is positioned {\it before} the first record in
3241 the result set after the query.  To retrieve the first record, call either
3242 \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} (only if backward scrolling
3243 cursors are available) or
3244 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.  Typically, no data from the
3245 result set is returned to the client driver until a request such as
3246 \helpref{wxDbTable::GetNext}{wxdbtablegetnext} is performed, so network
3247 traffic and database load are not overwhelmed transmitting data until the
3248 data is actually requested by the client.  This behavior is solely dependent
3249 on the ODBC driver though, so refer to the ODBC driver's reference material
3250 for information on its behaviors.
3251
3252 Values in the bound columns' memory variables are undefined after executing a
3253 call to this function and remain that way until a row in the result set is
3254 requested to be returned.
3255
3256 The wxDbTable::Query() function is defined as "virtual" so that it may be
3257 overridden for application specific purposes.
3258
3259 \normalbox{Be sure to set the wxDbTable's "where", "orderBy", and "from"
3260 member variables to "" if they are not to be used in the query.  Otherwise,
3261 the results returned may have unexpected results (or no results) due to
3262 improper or incorrect query parameters constructed from the uninitialized
3263 clauses.}
3264
3265 \wxheading{Example}
3266
3267 \begin{verbatim}
3268     // Incomplete code sample
3269     parts->SetWhereClause("DESCRIPTION = 'FOOD'");
3270     parts->SetOrderByClause("EXPIRATION_DATE");
3271     parts->SetFromClause("");
3272     // Query the records based on the where, orderBy and from clauses
3273     // specified above
3274     parts->Query();
3275     // Display all records queried
3276     while(parts->GetNext())
3277         dispPart(parts);  // user defined function
3278 \end{verbatim}
3279
3280 \membersection{wxDbTable::QueryBySqlStmt}\label{wxdbtablequerybysqlstmt}
3281
3282 \func{bool}{QueryBySqlStmt}{\param{const wxString \&}{pSqlStmt}}
3283
3284 Performs a query against the datasource by accepting and passing verbatim the
3285 SQL SELECT statement passed to the function.
3286
3287 \wxheading{Parameters}
3288
3289 \docparam{pSqlStmt}{Pointer to the SQL SELECT statement to be executed.}
3290
3291 \wxheading{Remarks}
3292
3293 This is the most powerful form of the query functions available.  This member
3294 function allows a programmer to write their own custom SQL SELECT statement
3295 for requesting data from the datasource.  This gives the programmer access
3296 to the full power of SQL for performing operations such as scalar functions,
3297 aggregate functions, table joins, and sub-queries, as well as datasource
3298 specific function calls.
3299
3300 The requirements of the SELECT statement are the following:
3301
3302 \begin{enumerate}
3303 \item Must return the correct number of columns.  In the derived
3304 wxDbTable constructor, it is specified how many columns are in
3305 the wxDbTable object. The SELECT statement must return exactly
3306 that many columns.
3307 \item The columns must be returned in the same sequence as specified
3308 when defining the bounds columns \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs},
3309 and the columns returned must be of the proper data type.  For
3310 example, if column 3 is defined in the wxDbTable bound column
3311 definitions to be a float, the SELECT statement must return a
3312 float for column 3 (e.g. PRICE * 1.10 to increase the price by
3313 10%).
3314 \item The ROWID can be included in your SELECT statement as the {\bf last}
3315 column selected, if the datasource supports it.  Use
3316 wxDbTable::CanUpdByROWID() to determine if the ROWID can be
3317 selected from the datasource.  If it can, much better
3318 performance can be achieved on updates and deletes by including
3319 the ROWID in the SELECT statement.
3320 \end{enumerate}
3321
3322 Even though data can be selected from multiple tables (joins) in your select
3323 statement, only the base table associated with this wxDbTable object
3324 is automatically updated through the ODBC class library.  Data from multiple
3325 tables can be selected for display purposes however.  Include columns in
3326 the wxDbTable object and mark them as non-updateable (See
3327 \helpref{wxDbColDef}{wxdbcoldef} for details).  This way columns can be
3328 selected and displayed from other tables, but only the base table will be
3329 updated automatically when performed through the
3330 \helpref{wxDbTable::Update}{wxdbtableupdate} function after using this type of
3331 query.  To update tables other than the base table, use the
3332 \helpref{wxDbTable::Update}{wxdbtableupdate} function passing a SQL statement.
3333
3334 After this function has been called, the cursor is positioned before the
3335 first record in the record set.  To retrieve the first record, call
3336 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3337 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3338
3339 \wxheading{Example}
3340
3341 \begin{verbatim}
3342     // Incomplete code samples
3343          wxString sqlStmt;
3344     sqlStmt = "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
3345                AND CONTAINER = 12";
3346     // Query the records using the SQL SELECT statement above
3347     parts->QueryBySqlStmt(sqlStmt);
3348     // Display all records queried
3349     while(parts->GetNext())
3350         dispPart(&parts);
3351
3352     Example SQL statements
3353     ----------------------
3354
3355     // Table Join returning 3 columns
3356     SELECT part_no, part_desc, sd_name
3357         from parts, storage_devices
3358         where parts.storage_device_id =
3359               storage_devices.storage_device_id
3360
3361     // Aggregate function returning total number of
3362     // parts in container 99
3363     SELECT count(*) from PARTS where container = 99
3364
3365     // Order by clause; ROWID, scalar function
3366     SELECT part_no, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
3367         from parts
3368         where warehouse = 10
3369         order by part_no desc           // descending order
3370
3371     // Subquery
3372     SELECT * from parts
3373         where container in (select container
3374         from storage_devices
3375             where device_id = 12)
3376 \end{verbatim}
3377
3378 \membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
3379
3380 \func{virtual bool }{QueryMatching}{\param{bool }{forUpdate=false},
3381 \param{bool }{distinct=false}}
3382
3383 QueryMatching allows querying of records from the table associated with
3384 the wxDbTable object by matching "columns" to values.
3385
3386 For example: To query the datasource for the row with a PART\_NUMBER column
3387 value of "32", clear all column variables of the wxDbTable object, set the
3388 PartNumber variable that is bound to the PART\_NUMBER column in the wxDbTable
3389 object to "32", and then call wxDbTable::QueryMatching().
3390
3391 \wxheading{Parameters}
3392
3393 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3394 as they are queried (SELECT ... FOR UPDATE).  If the RDBMS is not capable of
3395 the FOR UPDATE clause, this argument is ignored.  See
3396 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3397 additional information regarding this argument.  Default is false.}
3398 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3399 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3400 applies to all columns returned in the result set, not individual columns.
3401 Default is false.}
3402
3403 \wxheading{Remarks}
3404
3405 The SQL WHERE clause is built by the ODBC class library based on all
3406 non-zero/non-NULL columns in your wxDbTable object.  Matches can be on one,
3407 many or all of the wxDbTable's columns.  The base table name is prepended
3408 to the column names in the event that the wxDbTable's FROM clause is non-null.
3409
3410 This function cannot be used to perform queries which will check for
3411 columns that are 0 or NULL, as the automatically constructed WHERE clause
3412 only will contain comparisons on column member variables that are
3413 non-zero/non-NULL.
3414
3415 The primary difference between this function and \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields}
3416 is that this function can query on any column(s) in the wxDbTable object.
3417 Note however that this may not always be very efficient.  Searching on
3418 non-indexed columns will always require a full table scan.
3419
3420 The cursor is positioned before the first record in the record set after
3421 the query is performed.  To retrieve the first record, the program must call
3422 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3423 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3424
3425 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3426 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3427 this function.
3428
3429 \wxheading{Example}
3430
3431 \begin{verbatim}
3432     // Incomplete code sample
3433     parts->ClearMemberVars();           // Set all columns to zero
3434     wxStrcpy(parts->PartNumber,"32");   // Set columns to query on
3435     parts->OnHold = true;
3436     parts->QueryMatching();             // Query
3437     // Display all records queried
3438     while(parts->GetNext())
3439         dispPart(parts);  // Some application defined function
3440 \end{verbatim}
3441
3442 \membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
3443
3444 \func{bool }{QueryOnKeyFields}{\param{bool }{forUpdate=false},
3445 \param{bool }{distinct=false}}
3446
3447 QueryOnKeyFields provides an easy mechanism to query records in the table
3448 associated with the wxDbTable object by the primary index column(s).  Simply
3449 assign the primary index column(s) values and then call this member function
3450 to retrieve the record.
3451
3452 Note that since primary indexes are always unique, this function implicitly
3453 always returns a single record from the database. The base table name is
3454 prepended to the column names in the event that the wxDbTable's FROM clause
3455 is non-null.
3456
3457 \wxheading{Parameters}
3458
3459 \docparam{forUpdate}{{\it OPTIONAL}.  Gives you the option of locking records
3460 as they are queried (SELECT ... FOR UPDATE).  If the RDBMS is not capable of
3461 the FOR UPDATE clause, this argument is ignored.  See
3462 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3463 additional information regarding this argument.  Default is false.}
3464 \docparam{distinct}{{\it OPTIONAL}.  Allows selection of only distinct values
3465 from the query (SELECT DISTINCT ... FROM ...).  The notion of DISTINCT
3466 applies to all columns returned in the result set, not individual columns.
3467 Default is false.}
3468
3469 \wxheading{Remarks}
3470
3471 The cursor is positioned before the first record in the record set after
3472 the query is performed.  To retrieve the first record, the program must call
3473 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3474 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3475
3476 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3477 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3478 this function.
3479
3480 \wxheading{Example}
3481
3482 \begin{verbatim}
3483     // Incomplete code sample
3484     wxStrcpy(parts->PartNumber, "32");
3485     parts->QueryOnKeyFields();
3486     // Display all records queried
3487     while(parts->GetNext())
3488         dispPart(parts);  // Some application defined function
3489 \end{verbatim}
3490
3491 \membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
3492
3493 \func{bool}{Refresh}{\void}
3494
3495 This function re-reads the bound columns into the memory variables, setting
3496 them to the current values stored on the disk.
3497
3498 The cursor position and result set are unaffected by calls to this function.
3499 (The one exception is in the case where the record to be refreshed has been
3500 deleted by some other user or transaction since it was originally retrieved
3501 as part of the result set.  For most datasources, the default behavior in
3502 this situation is to return the value that was originally queried for the
3503 result set, even though it has been deleted from the database.  But this is
3504 datasource dependent, and should be tested before relying on this behavior.)
3505
3506 \wxheading{Remarks}
3507
3508 This routine is only guaranteed to work if the table has a unique primary
3509 index defined for it.  Otherwise, more than one record may be fetched and
3510 there is no guarantee that the correct record will be refreshed.  The
3511 table's columns are refreshed to reflect the current data in the database.
3512
3513 \membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
3514
3515 \func{void}{SetColDefs}{\param{UWORD }{index}, \param{const wxString \&}{fieldName},
3516 \param{int }{dataType}, \param{void *}{pData}, \param{SWORD }{cType},
3517 \param{int }{size}, \param{bool }{keyField = false}, \param{bool }{upd = true},
3518 \param{bool }{insAllow = true}, \param{bool }{derivedCol = false}}
3519
3520 \func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{UWORD }{numCols}}
3521
3522 \wxheading{Parameters}
3523
3524 \docparam{index}{Column number (0 to n-1, where n is the number of columns
3525 specified as being defined for this wxDbTable instance when the
3526 wxDbTable constructor was called.}
3527 \docparam{fieldName}{Column name from the associated data table.}
3528 \docparam{dataType}{Logical data type.  Valid logical types include:}
3529
3530 \begin{verbatim}
3531     DB_DATA_TYPE_VARCHAR        : strings
3532     DB_DATA_TYPE_INTEGER        : non-floating point numbers
3533     DB_DATA_TYPE_FLOAT          : floating point numbers
3534     DB_DATA_TYPE_DATE           : dates
3535 \end{verbatim}
3536
3537 \docparam{pData}{Pointer to the data object that will hold the column's
3538 value when a row of data is returned from the datasource.}
3539 \docparam{cType}{SQL C Type.  This defines the data type that the SQL
3540 representation of the data is converted to to be stored in {\it pData}.
3541 Other valid types are available also, but these are the most common ones:}
3542
3543 \begin{verbatim}
3544     SQL_C_CHAR      // strings
3545     SQL_C_LONG
3546     SQL_C_ULONG
3547     SQL_C_SHORT
3548     SQL_C_USHORT
3549     SQL_C_FLOAT
3550     SQL_C_DOUBLE
3551     SQL_C_NUMERIC
3552     SQL_C_TIMESTAMP
3553
3554     SQL_C_BOOLEAN   // defined in db.h
3555     SQL_C_ENUM      // defined in db.h
3556 \end{verbatim}
3557
3558 \docparam{size}{Maximum size in bytes of the {\it pData} object.}
3559 \docparam{keyField}{{\it OPTIONAL}.  Indicates if this column is part of the
3560 primary index.  Default is false.}
3561 \docparam{upd}{{\it OPTIONAL}.  Are updates allowed on this column?
3562 Default is true.}
3563 \docparam{insAllow}{{\it OPTIONAL}.  Inserts allowed on this column?
3564 Default is true.}
3565 \docparam{derivedCol}{{\it OPTIONAL}.  Is this a derived column (non-base
3566 table column for query only)?  Default is false.}
3567
3568 \docparam{colInfs}{Pointer to an array of wxDbColInf instances which contains
3569 all the information necessary to create {\it numCols} column definitions.}
3570 \docparam{numCols}{Number of elements of wxDbColInf type that are pointed
3571 to by {\it colInfs}, which are to have column definitions created from them.}
3572
3573 \wxheading{Remarks}
3574
3575 If {\it pData} is to hold a string of characters, be sure to include enough
3576 space for the NULL terminator in pData and in the byte count of {\it size}.
3577
3578 Both forms of this function provide a shortcut for defining the columns in
3579 your wxDbTable object.  Use this function in any derived wxDbTable
3580 constructor when describing the column/columns in the wxDbTable object.
3581
3582 The second form of this function is primarily used when the
3583 \helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
3584 datasource for the column definitions, so that the column definitions are
3585 already stored in wxDbColInf form.  One example use of using
3586 \helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
3587 a data table existed in one datasource, and the table's column definitions
3588 were to be copied over to another datasource or table.
3589
3590 \wxheading{Example}
3591
3592 \begin{verbatim}
3593     // Long way not using this function
3594     wxStrcpy(colDefs[0].ColName, "PART_NO");
3595     colDefs[0].DbDataType   = DB_DATA_TYPE_VARCHAR;
3596     colDefs[0].PtrDataObj   = PartNumber;
3597     colDefs[0].SqlCtype     = SQL_C_CHAR;
3598     colDefs[0].SzDataObj    = PART_NUMBER_LEN;
3599     colDefs[0].KeyField     = true;
3600     colDefs[0].Updateable   = false;
3601     colDefs[0].InsertAllowed= true;
3602     colDefs[0].DerivedCol   = false;
3603
3604     // Shortcut using this function
3605     SetColDefs(0, "PART_NUMBER", DB_DATA_TYPE_VARCHAR, PartNumber,
3606                SQL_C_CHAR, PART_NUMBER_LEN, true, false,true,false);
3607 \end{verbatim}
3608
3609 \membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
3610
3611 \func{bool}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB\_DEFAULT\_CURSOR}}
3612
3613 \wxheading{Parameters}
3614
3615 \docparam{hstmtActivate}{{\it OPTIONAL}.  Pointer to the cursor that is to
3616 become the current cursor.  Passing no cursor handle will reset the cursor
3617 back to the wxDbTable's default (original) cursor that was created when the
3618 wxDbTable instance was first created.  Default is wxDB\_DEFAULT\_CURSOR.}
3619
3620 \wxheading{Remarks}
3621
3622 When swapping between cursors, the member variables of the wxDbTable object
3623 are automatically refreshed with the column values of the row that the
3624 current cursor is positioned at (if any).  If the cursor is not positioned,
3625 then the data in member variables is undefined.
3626
3627 The only way to return back to the cursor that was in use before this
3628 function was called is to programmatically determine the current cursor's HSTMT
3629 {\bf BEFORE} calling this function using \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor}
3630 and saving a pointer to that cursor.
3631
3632 \wxheading{See also}
3633
3634 \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor},
3635 \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor},
3636 \helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}
3637
3638 \membersection{wxDbTable::SetFromClause}\label{wxdbtablesetfromclause}
3639
3640 \func{void}{SetFromClause}{\param{const wxString \&}{From}}
3641
3642 Accessor function for setting the private class member wxDbTable::from
3643 that indicates what other tables should be outer joined with the wxDbTable's
3644 base table for access to the columns in those other tables.
3645
3646 Synonym to this function is one form of \helpref{wxDbTable::From}{wxdbtablefrom}
3647
3648 \wxheading{Parameters}
3649
3650 \docparam{From}{A comma separated list of table names that are to be outer
3651 joined with the base table's columns so that the joined table's columns
3652 may be returned in the result set or used as a portion of a comparison with
3653 the base table's columns.  NOTE that the base tables name must NOT be included
3654 in the FROM clause, as it is automatically included by the wxDbTable class
3655 in constructing query statements.}
3656
3657 \wxheading{Remarks}
3658
3659 Used by the \helpref{wxDbTable::Query}{wxdbtablequery} and
3660 \helpref{wxDbTable::Count}{wxdbtablecount} member functions to allow outer
3661 joining of records from multiple tables.
3662
3663 Do {\bf not} include the keyword "FROM" when setting the FROM clause.
3664
3665 If using the FROM clause when performing a query, be certain to include in
3666 the corresponding WHERE clause a comparison of a column from either the base
3667 table or one of the other joined tables to each other joined table to ensure
3668 the datasource knows on which column values the tables should be joined on.
3669
3670 \wxheading{Example}
3671
3672 \begin{verbatim}
3673     ...
3674     // Base table is the "LOCATION" table, and it is being
3675     // outer joined to the "PART" table via the the field "PART_NUMBER"
3676     // that can be related between the two tables.
3677     location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
3678     location->SetFromClause("PART");
3679     ...
3680 \end{verbatim}
3681
3682 \wxheading{See also}
3683
3684 \helpref{wxDbTable::From}{wxdbtablefrom},
3685 \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
3686
3687 \membersection{wxDbTable::SetColNull}\label{wxdbtablesetcolnull}
3688
3689 \func{bool}{SetColNull}{\param{UWORD }{colNo}, \param{bool }{set=true}}
3690
3691 \func{bool}{SetColNull}{\param{const wxString \&}{colName},
3692 \param{bool }{set=true}}
3693
3694 Both forms of this function allow a member variable representing a column
3695 in the table associated with this wxDbTable object to be set to NULL.
3696
3697 The first form allows the column to be set by the index into the column
3698 definitions used to create the wxDbTable instance, while the second allows
3699 the actual column name to be specified.
3700
3701 \wxheading{Parameters}
3702
3703 \docparam{colNo}{Index into the column definitions used when first defining
3704 this wxDbTable object.}
3705 \docparam{colName}{Actual data table column name that is to be set to NULL.}
3706 \docparam{set}{Whether the column is set to NULL or not.  Passing true sets
3707 the column to NULL, passing false sets the column to be non-NULL.  Default is
3708 true.}
3709
3710 \wxheading{Remarks}
3711
3712 No database updates are done by this function.  It only operates on the
3713 member variables in memory.  Use and insert or update function to store this
3714 value to disk.
3715
3716 \membersection{wxDbTable::SetOrderByClause}\label{wxdbtablesetorderbyclause}
3717
3718 \func{void}{SetOrderByClause}{\param{const wxString \&}{OrderBy}}
3719
3720 Accessor function for setting the private class member wxDbTable::orderBy
3721 which determines sequence/ordering of the rows returned in the result set
3722 of a query.
3723
3724 A synonym to this function is one form of the function \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
3725
3726 \wxheading{Parameters}
3727
3728 \docparam{OrderBy}{A comma separated list of column names that indicate the
3729 alphabetized sorting sequence that the result set is to be returned in.  If
3730 a FROM clause has also been specified, each column name specified in the
3731 ORDER BY clause should be prefaced with the table name to which the column
3732 belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
3733
3734 \wxheading{Remarks}
3735
3736 Do {\bf not} include the keywords "ORDER BY" when setting the ORDER BY clause.
3737
3738 \wxheading{Example}
3739
3740 \begin{verbatim}
3741     ...
3742     parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
3743     ...
3744
3745     ...
3746     location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
3747     ...
3748 \end{verbatim}
3749
3750 \wxheading{See also}
3751
3752 \helpref{wxDbTable::OrderBy}{wxdbtableorderby},
3753 \helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
3754
3755 \membersection{wxDbTable::SetQueryTimeout}\label{wxdbtablesetquerytimeout}
3756
3757 \func{bool}{SetQueryTimeout}{\param{UDWORD }{nSeconds}}
3758
3759 Allows a time period to be set as the timeout period for queries.
3760
3761 \wxheading{Parameters}
3762
3763 \docparam{nSeconds}{The number of seconds to wait for the query to complete
3764 before timing out.}
3765
3766 \wxheading{Remarks}
3767
3768 Neither Oracle or Access support this function as of yet.  Other databases
3769 should be evaluated for support before depending on this function working
3770 correctly.
3771
3772 \membersection{wxDbTable::SetWhereClause}\label{wxdbtablesetwhereclause}
3773
3774 \func{void}{SetWhereClause}{\param{const wxString \&}{Where}}
3775
3776 Accessor function for setting the private class member wxDbTable::where
3777 that determines which rows are returned in the result set by the datasource.
3778
3779 A synonym to this function is one form of the function \helpref{wxDbTable::Where}{wxdbtablewhere}
3780
3781 \wxheading{Parameters}
3782
3783 \docparam{Where}{SQL "where" clause.  This clause can contain any SQL language
3784 that is legal in standard where clauses.  If a FROM clause has also been
3785 specified, each column name specified in the ORDER BY clause should be
3786 prefaced with the table name to which the column belongs using DOT notation
3787 (TABLE\_NAME.COLUMN\_NAME).}
3788
3789 \wxheading{Remarks}
3790
3791 Do {\bf not} include the keywords "WHERE" when setting the WHERE clause.
3792
3793 \wxheading{Example}
3794
3795 \begin{verbatim}
3796     ...
3797     // Simple where clause
3798     parts->SetWhereClause("PART_NUMBER = '32'");
3799     ...
3800     // Any comparison operators
3801     parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER%'");
3802     ...
3803     // Multiple comparisons, including a function call
3804     parts->Where("QTY > 0 AND {fn UCASE(PART_DESCRIP)} LIKE '%DRILL%'");
3805     ...
3806     // Using parameters and multiple logical combinations
3807     parts->Where("((QTY > 10) OR (ON_ORDER > 0)) AND ON_HOLD = 0");
3808     ...
3809     // This query uses an outer join (requiring a FROM clause also)
3810     // that joins the PART and LOCATION table on he common field
3811     // PART_NUMBER.
3812     parts->Where("PART.ON_HOLD = 0 AND \
3813                   PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
3814                   LOCATION.PART_NUMBER > 0");
3815 \end{verbatim}
3816
3817 \wxheading{See also}
3818
3819 \helpref{wxDbTable::Where}{wxdbtablewhere},
3820 \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
3821
3822 \membersection{wxDbTable::Update}\label{wxdbtableupdate}
3823
3824 \func{bool }{Update}{\void}
3825
3826 \func{bool }{Update}{\param{const wxString \&}{pSqlStmt}}
3827
3828 The first form of this function will update the row that the current cursor
3829 is currently positioned at with the values in the memory variables that
3830 are bound to the columns.  The actual SQL statement to perform the update
3831 is automatically created by the ODBC class, and then executed.
3832
3833 The second form of the function allows full access through SQL statements for
3834 updating records in the database.  Write any valid SQL UPDATE statement and
3835 submit it to this function for execution.  Sophisticated updates can be
3836 performed using the full power of the SQL dialect. The full SQL statement
3837 must have  the exact syntax required by the driver/datasource for performing
3838 the update.  This usually is in the form of:
3839
3840 \begin{verbatim}
3841     UPDATE tablename SET col1=X, col2=Y, ... where ...
3842 \end{verbatim}
3843
3844 \wxheading{Parameters}
3845
3846 \docparam{pSqlStmt}{Pointer to SQL UPDATE statement to be executed.}
3847
3848 \wxheading{Remarks}
3849
3850 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3851 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3852 this function to commit or rollback the update.
3853
3854 \wxheading{Example}
3855
3856 \begin{verbatim}
3857          wxString sqlStmt;
3858     sqlStmt = "update PART set QTY = 0 where PART_NUMBER = '32'";
3859 \end{verbatim}
3860
3861 \membersection{wxDbTable::UpdateWhere}\label{wxdbtableupdatewhere}
3862
3863 \func{bool}{UpdateWhere}{\param{const wxString \&}{pWhereClause}}
3864
3865 Performs updates to the base table of the wxDbTable object, updating only the
3866 rows which match the criteria specified in the {\it pWhereClause}.
3867
3868 All columns that are bound to member variables for this wxDbTable instance
3869 that were defined with the "updateable" parameter set to true will be updated
3870 with the information currently held in the memory variable.
3871
3872 \wxheading{Parameters}
3873
3874 \docparam{pWhereClause}{Pointer to a valid SQL WHERE clause.  Do not
3875 include the keyword 'WHERE'.}
3876
3877 \wxheading{Remarks}
3878
3879 Care should be used when updating columns that are part of indexes with
3880 this function so as not to violate an unique key constraints.
3881
3882 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3883 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3884 this function to commit or rollback the update(s).
3885
3886 \membersection{wxDbTable::Where}\label{wxdbtablewhere}
3887
3888 \func{const wxString \&}{Where}{}
3889
3890 \func{void}{Where}{\param{const wxString\& }{Where}}
3891
3892 Accessor function for the private class member wxDbTable::where.  Can be used
3893 as a synonym for \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
3894 (the first form of this function) to return the current where clause or
3895 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} (the second form
3896 of this function) to set the where clause for this table instance.
3897
3898 \wxheading{Parameters}
3899
3900 \docparam{Where}{A valid SQL WHERE clause.  Do not include the keyword 'WHERE'.}
3901
3902 \wxheading{Return value}
3903
3904 The first form of this function returns the current value of the wxDbTable
3905 member variable ::where.
3906
3907 The second form of the function has no return value, as it will always set
3908 the where clause successfully.
3909
3910 \wxheading{See also}
3911
3912 \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause},
3913 \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3914
3915 \membersection{wxDbTable::operator $++$}\label{wxdbtableplusplus}
3916
3917 \func{bool}{operator $++$}{\void}
3918
3919 Synonym for \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
3920
3921 \wxheading{See also}
3922
3923 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
3924
3925 \membersection{wxDbTable::operator $--$}\label{wxdbtableminusminus}
3926
3927 \func{bool}{operator $--$}{\void}
3928
3929 Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
3930
3931 \wxheading{See also}
3932
3933 \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
3934
3935 \section{\class{wxDbTableInf}}\label{wxdbtableinf}
3936
3937 \begin{verbatim}
3938     tableName[0]    = 0;
3939     tableType[0]    = 0;
3940     tableRemarks[0] = 0;
3941     numCols         = 0;
3942     pColInf         = NULL;
3943 \end{verbatim}
3944
3945 Currently only used by \helpref{wxDb::GetCatalog}{wxdbgetcatalog} internally
3946 and \helpref{wxDbInf}{wxdbinf} class, but may be used in future releases for
3947 user functions.  Contains information describing the table (Name, type, etc).
3948 A pointer to a wxDbColInf array instance is included so a program can create a
3949 \helpref{wxDbColInf}{wxdbcolinf} array instance (using
3950 \helpref{wxDb::GetColumns}{wxdbgetcolumns})
3951 to maintain all information about the columns of a table in one memory
3952 structure.
3953
3954 Eventually, accessor functions will be added for this class
3955
3956 See the \helpref{database classes overview}{odbcoverview} for
3957 an introduction to using the ODBC classes.
3958
3959 \membersection{wxDbTableInf::Initialize}\label{wxdbtableinfinitialize}
3960
3961 Simply initializes all member variables to a cleared state.  Called by
3962 the constructor automatically.
3963
3964 \section{\class{wxDbGridColInfo}}\label{wxdbgridcolinfo}
3965
3966 This class is used  to define columns to be shown, names of the columns,
3967 order and type of data, when using \helpref{wxdbGridTableBase}{wxdbgridtablebase} to display
3968 a Table or query in a \helpref{wxGrid}{wxgrid}
3969
3970 See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} for
3971 an introduction to using the wxDbGrid classes.
3972
3973 \wxheading{Include files}
3974
3975 <wx/dbgrid.h>
3976
3977 \latexignore{\rtfignore{\wxheading{Members}}}
3978
3979 \membersection{wxDbGridColInfo::wxDbGridColInfo}\label{wxdbgridcolinfoctor}
3980
3981 \func{}{wxDbGridColInfo}{\param{int }{colNo}, \param{wxString }{type},
3982   \param{wxString }{title}, \param{wxDbGridColInfo *}{next}}
3983
3984 Default constructor. See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
3985 see two different ways for adding columns.
3986
3987
3988 \wxheading{Parameters}
3989
3990 \docparam{colNo}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
3991 \docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
3992  use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
3993 \docparam{title}{The column label to be used in the grid display}
3994 \docparam{next}{A pointer to the next wxDbGridColInfo structure if using one-step
3995 construction, NULL  terminates the list. Use Null also if using two step construction.}
3996 See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
3997 see two different ways for adding columns.
3998
3999 \membersection{wxDbGridColInfo::\destruct{wxDbGridColInfo}}
4000
4001 \func{}{\destruct{wxDbGridColInfo}}{}
4002
4003 Destructor.
4004
4005 \membersection{wxDbGridColInfo::AddColInfo}\label{wxdbgridcolinfoaddcolinfo}
4006
4007 \func{void}{AddColInfo}{\param{int }{colNo},
4008 \param{wxString }{type}, \param{wxString }{title}}
4009
4010 Use this member function for adding columns. See the database
4011 grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
4012 see two different ways for adding columns.
4013
4014 It is important to note that this class is merely a specifier to the \helpref{wxDbGridTableBase}{wxdbgridtablebase}
4015 constructor. Changes made to this datatype after the \helpref{wxDbGridTableBase}{wxdbgridtablebase} is called will
4016 not have any effect.
4017
4018 \wxheading{Parameters}
4019 \docparam{colNo}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
4020 \docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
4021  use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
4022 \docparam{title}{The column label to be used in the grid display}
4023
4024 \wxheading{Remarks}
4025
4026 As wxDbTable must be defined with to have columns which match those  to by a wxDbGridColInfo
4027 info structure as this is the structure which informs the grid of how you want to display your
4028 \helpref{wxDbTable}{wxdbtable}. If no datatype conversion or the referenced column number does not exist the
4029 the behavior is undefined.
4030
4031 See the example at \helpref{wxDbGridColInfo::wxDbGridColInfo}{wxdbgridcolinfoctor}.
4032
4033 \section{\class{wxDbGridTableBase}}\label{wxdbgridtablebase}
4034
4035 You can view a database table in a grid using this class.
4036
4037 If you are deriving your own wxDbTable subclass for your table , then you may consider
4038 overriding GetCol() and SetCol() to provide calculated fields. This does work but care should
4039 be taken when using wxDbGridTableBase in this way.
4040
4041 The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable
4042 object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable
4043 when an new on is assigned or wxGridTableBase's destructor is called.
4044 However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true);
4045 is  an error. If you need to requery an table object the preferred way is
4046 that the client keeps ownership.
4047
4048 \wxheading{Derived From}
4049
4050 \helpref{wxGridTableBase}{wxgridtablebase}
4051
4052 \wxheading{Include files}
4053
4054 <wx/dbgrid.h>
4055
4056
4057 \wxheading{Example}
4058
4059 \begin{verbatim}
4060         // First step, let's define wxDbTable
4061         int numColumns = 2;
4062         wxDbTable *table = new wxDbTable (db, tblName, numColumns);
4063         int int_var;
4064         wxChar string_name[255];
4065         table->SetColDef (0, "column 0", DB_DATA_TYPE_INTEGER, &int_var,
4066                         SQL_C_LONG, sizeof(int_var), true);
4067         table->SetColDef (1, "column 1", DB_DATA_TYPE_VARCHAR, &string_name,
4068                         SQL_C_LONG, sizeof(string_name), false);
4069
4070     // now let's define columns in the grid
4071
4072     // first way to do it
4073     wxDbGridColInfo *columns;
4074     columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column",
4075               new wxDbGridColInfo(1, wxGRID_VALUE_STRING, "second column",
4076               NULL);
4077
4078     // second way to do it
4079     wxDbGridColInfo *columns;
4080     // first column is special
4081     columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column", NULL);
4082     // all the rest
4083     columns->AddColInfo (1, wxGRID_VALUE_STRING, "second column");
4084
4085     // second way may be better when columns are not known at compile time
4086
4087     // now, let's open the table and make a Query()
4088     table->Open();
4089     // this step is very important
4090     table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
4091     // in the grid we will see only the rows of the result query
4092     m_dbTable->Query();
4093
4094     wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, true);
4095     delete columns;  // not needed anymore
4096     wxGrid *grid = new wxGrid ( ... );
4097     grid->SetTable(dbgrid, true);
4098     grid->Fit();
4099 \end{verbatim}
4100
4101
4102 \wxheading{Include files}
4103
4104 <wx/dbgrid.h>
4105
4106 \wxheading{Helper classes and data structures}
4107
4108 \membersection{wxDbGridTableBase::wxDbGridTableBase}\label{wxdbgridtablebaseconstr}
4109
4110 \func{}{wxDbGridTableBase}{\param{wxDbTable *}{tab}, \param{wxDbGridColInfo *}{ColInfo},
4111   \param{int }{count = wxUSE\_QUERY}, \param{bool }{takeOwnership = true}}
4112
4113 Constructor.
4114
4115 \wxheading{Parameters}
4116
4117 \docparam{tab}{ The database table you want to display. Must be opened and queried before display the grid.
4118 See the example \helpref{above}{wxdbgridtablebase}.}
4119 \docparam{ColInfo}{ Columns titles, and other values. See \helpref{wxDbGridColInfo}{wxdbgridcolinfo}.}
4120 \docparam{count}{You can use a query result set (wxUSE\_QUERY, to use wxDbTable::Count(wxDbTable::Count()
4121  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 }
4122
4123 \docparam{takeOwnership}{ If true, this class deletes wxDbTable when it stops
4124 referring to it, if false application must
4125 take care of deleting it.  }
4126
4127 \membersection{wxDbGridTableBase::ValidateRow}\label{wxdbgridtablebasevalidate}
4128
4129 \func{void}{ValidateRow}{\param{int }{row}}
4130
4131 It ensures that the row data is fetched from the database, and it the wxDbTable local buffer,
4132 the row number passed should be the grid row.
4133
4134 \wxheading{Parameters}
4135
4136 \docparam{row}{ Row where validation must be done. }
4137
4138 \membersection{wxDbGridTableBase::UpdateRow}\label{wxdbgridtablebaseupdaterow}
4139
4140 \func{bool}{UpdateRow}{\param{int }{row}}
4141
4142 If row has changed it forces that row to be written back to the database, however support
4143 for detecting whether insert/update is required is currently not in wxDbTable, so this
4144 function is currently unsupported.
4145
4146 \wxheading{Parameters}
4147
4148 \docparam{row}{ Row you want to update. }
4149
4150 \membersection{wxDbGridTableBase::AssignDbTable}\label{wxdbgridtablebaseassigndbtable}
4151
4152 \func{bool}{AssignDbTable}{\param{wxDbTable *}{tab},\param{int }{count = wxUSE\_QUERY},
4153 \param{bool }{takeOwnership = true}}
4154
4155 Resets the grid for using with a new database table, but using the same columns definition.
4156 This can be useful when re-querying the database and want to see the changes.
4157
4158 \wxheading{Parameters}
4159
4160 \docparam{tab}{ Database table you want to assign to the grid. }
4161 \docparam{count}{ Number of rows you want to show or wxUSE\_QUERY for using a query. }
4162 \docparam{takeOwnership}{ If false, user must take care of deleting tab after deleting
4163 the wxDbGridTableBase. If true, deletion is made by destructor class. }
4164