+\membersection{wxDb::GetData}\label{wxdbgetdata}
+
+\func{bool}{GetData}{\param{UWORD}{ colNumber}, \param{SWORD}{ cType},
+\param{PTR}{ pData}, \param{SDWORD}{ maxLen}, \param{SDWORD FAR *}{ cbReturned} }
+
+Used to retrieve result set data without binding column values to memory
+variables (i.e. not using a wxDbTable instance to access table data).
+
+\wxheading{Parameters}
+
+\docparam{colNumber}{Ordinal number of the desired column in the result set to be
+returned.}
+\docparam{cType}{The C data type that is to be returned. See a partial list
+in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}}
+\docparam{pData}{Memory buffer which will hold the data returned by the call
+to this function.}
+\docparam{maxLen}{Maximum size of the buffer {\it 'pData'} in characters.
+NOTE: Not UNICODE safe. If this is a numeric field, a value of 0 may be
+passed for this parameter, as the API knows the size of the expected return
+value.}
+\docparam{cbReturned}{Pointer to the buffer containing the length of the
+actual data returned. If this value comes back as SQL\_NULL\_DATA, then the
+\helpref{wxDb::GetData}{wxdbgetdata} call has failed.}
+
+\wxheading{See also}
+
+\helpref{wxDb::GetNext}{wxdbgetnext}, \helpref{wxDb::ExecSql}{wxdbexecsql}
+
+\wxheading{Example}
+
+\begin{verbatim}
+ SDWORD cb;
+ ULONG reqQty;
+ wxString sqlStmt;
+ sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
+ PART_RECID = 1450 AND REQUIRED_QTY > PICKED_QTY";
+
+ // Perform the query
+ if (!pDb->ExecSql(sqlStmt.c_str()))
+ {
+ // ERROR
+ return(0);
+ }
+
+ // Request the first row of the result set
+ if (!pDb->GetNext())
+ {
+ // ERROR
+ return(0);
+ }
+
+ // Read column #1 of the row returned by the call to ::GetNext()
+ // and return the value in 'reqQty'
+ if (!pDb->GetData(1, SQL_C_ULONG, &reqQty, 0, &cb))
+ {
+ // ERROR
+ return(0);
+ }
+
+ // Check for a NULL result
+ if (cb == SQL_NULL_DATA)
+ return(0);
+\end{verbatim}
+
+\wxheading{Remarks}
+
+When requesting multiple columns to be returned from the result set (for example, the SQL query
+requested 3 columns be returned), the calls to this function must request the columns in ordinal
+sequence (1,2,3 or 1,3 or 2,3).
+
+\membersection{wxDb::GetDatabaseName}\label{wxdbgetdatabasename}
+
+\func{const wxChar *}{GetDatabaseName}{\void}
+
+Returns the name of the database engine.
+
+\membersection{wxDb::GetDatasourceName}\label{wxdbgetdatasourcename}
+
+\func{const wxString \&}{GetDatasourceName}{\void}
+
+Returns the ODBC datasource name.
+
+\membersection{wxDb::GetHDBC}\label{wxdbgethdbc}
+
+\func{HDBC}{GetHDBC}{\void}
+
+Returns the ODBC handle to the database connection.
+
+\membersection{wxDb::GetHENV}\label{wxdbgethenv}
+
+\func{HENV}{GetHENV}{\void}
+
+Returns the ODBC environment handle.
+
+\membersection{wxDb::GetHSTMT}\label{wxdbgethstmt}
+
+\func{HSTMT}{GetHSTMT}{\void}
+
+Returns the ODBC statement handle associated with this database connection.
+
+\membersection{wxDb::GetKeyFields}\label{wxdbgetkeyfields}
+
+\func{int }{GetKeyFields}{\param{const wxString \&}{tableName}, \param{wxDbColInf *}{colInf}, \param{UWORD }{numColumns}}
+
+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.
+
+This function is primarily for use by the \helpref{wxDb::GetColumns}{wxdbgetcolumns} function, but may be called if desired from the client application.
+
+\wxheading{Parameters}
+
+\docparam{tableName}{Name of the table for which the columns will be evaluated as to their inclusion in any indexes.}
+\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.}
+\docparam{numColumns}{Number of columns defined in the instance of colInf.}
+
+\wxheading{Return value}
+
+Currently always returns true.
+
+\wxheading{See also}
+
+\helpref{wxDbColInf}{wxdbcolinf}, \helpref{wxDb::GetColumns}{wxdbgetcolumns}
+
+\membersection{wxDb::GetNext}\label{wxdbgetnext}
+
+\func{bool}{GetNext}{\void}
+
+Called after executing a query, this function requests the next row
+in the result set after the current position of the cursor.
+
+\wxheading{See also}
+
+\helpref{wxDb::ExecSql}{wxdbexecsql}, \helpref{wxDb::GetData}{wxdbgetdata}
+
+\membersection{wxDb::GetNextError}\label{wxdbgetnexterror}
+
+\func{bool}{GetNextError}{\param{HENV}{ aHenv},
+\param{HDBC}{ aHdbc = SQL\_NULL\_HDBC}, \param{HSTMT}{ aHstmt = SQL\_NULL\_HSTMT}}
+
+\wxheading{Parameters}
+
+\docparam{aHenv}{A handle to the ODBC environment.}
+\docparam{aHdbc}{{\it OPTIONAL.} A handle to the ODBC connection. Pass this
+in if the ODBC function call that failed required a hdbc or hstmt argument.}
+\docparam{AHstmt}{{\it OPTIONAL.}A handle to the ODBC statement being executed
+against. Pass this in if the ODBC function call that failed requires a
+hstmt argument.}
+
+\wxheading{Example}
+
+\begin{verbatim}
+ if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
+ {
+ return(db.GetNextError(db.henv, db.hdbc, hstmt));
+ }
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxDb::DispNextError}{wxdbdispnexterror},
+\helpref{wxDb::DispAllErrors}{wxdbdispallerrors}
+
+
+\membersection{wxDb::GetPassword}\label{wxdbgetpassword}
+
+\func{const wxString \&}{GetPassword}{\void}
+
+Returns the password used to establish this connection to the datasource.
+
+
+\membersection{wxDb::GetTableCount}\label{wxdbgettablecount}
+
+\func{int }{GetTableCount}{\void}
+
+Returns the number of wxDbTable() instances currently using this datasource
+connection.
+
+
+\membersection{wxDb::GetUsername}\label{wxdbgetusername}
+
+\func{const wxString \&}{GetUsername}{\void}
+
+Returns the user name (uid) used to establish this connection to the
+datasource.
+
+
+\membersection{wxDb::Grant}\label{wxdbgrant}
+
+\func{bool}{Grant}{\param{int }{privileges}, \param{const wxString \&}{tableName},
+\param{const wxString \&}{userList = "PUBLIC"}}
+
+Use this member function to GRANT privileges to users for accessing tables in
+the datasource.
+
+\wxheading{Parameters}
+
+\docparam{privileges}{Use this argument to select which privileges you want to
+grant. Pass DB\_GRANT\_ALL to grant all privileges. To grant individual
+privileges pass one or more of the following OR'd together:}
+
+\begin{verbatim}
+ DB_GRANT_SELECT = 1
+ DB_GRANT_INSERT = 2
+ DB_GRANT_UPDATE = 4
+ DB_GRANT_DELETE = 8
+ DB_GRANT_ALL = DB_GRANT_SELECT | DB_GRANT_INSERT |
+ DB_GRANT_UPDATE | DB_GRANT_DELETE
+\end{verbatim}
+
+\docparam{tableName}{The name of the table you wish to grant privileges on.}
+\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.}
+
+\wxheading{Remarks}
+
+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.
+
+The currently logged in user must have sufficient grantor privileges for this
+function to be able to successfully grant the indicated privileges.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
+\end{verbatim}
+
+\membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}
+
+\func{bool}{IsFwdOnlyCursors}{\void}
+
+This setting indicates whether this database connection was created
+as being capable of using only forward scrolling cursors.
+
+This function does NOT indicate if the ODBC driver or datasource supports
+backward scrolling cursors. There is no standard way of detecting if the
+driver or datasource can support backward scrolling cursors.
+
+If a wxDb instance was created as being capable of only forward scrolling
+cursors, then even if the datasource and ODBC driver support backward
+scrolling cursors, tables using this database connection would only be able
+to use forward scrolling cursors.
+
+The default setting of whether a wxDb connection to a database allows
+forward-only or also backward scrolling cursors is defined in setup.h by the
+value of wxODBC\_FWD\_ONLY\_CURSORS. This default setting can be overridden
+when the wxDb connection is initially created (see
+\helpref{wxDb constructor}{wxdbctor} and \helpref{wxDbGetConnection}{wxdbfunctions}).
+
+\wxheading{Return value}
+
+Returns true if this datasource connection is defined as using only forward
+scrolling cursors, or false if the connection is defined as being allowed to
+use backward scrolling cursors and their associated functions (see note above).
+
+\wxheading{Remarks}
+
+Added as of wxWidgets v2.4 release, this function is a renamed version of
+wxDb::FwdOnlyCursors() to match the normal wxWidgets naming conventions for
+class member functions.
+
+This function is not available in versions prior to v2.4. You should
+use \helpref{wxDb::FwdOnlyCursors}{wxdbfwdonlycursors} for wxWidgets
+versions prior to 2.4.
+
+\wxheading{See also}
+
+\helpref{wxDb constructor}{wxdbctor}, \helpref{wxDbGetConnection}{wxdbfunctions}
+
+\membersection{wxDb::IsOpen}\label{wxdbisopen}
+
+\func{bool}{IsOpen}{\void}
+
+Indicates whether the database connection to the datasource is currently
+opened.
+
+\wxheading{Remarks}
+
+This function may indicate that the database connection is open, even if
+the call to \helpref{wxDb::Open}{wxdbopen} may have failed to fully
+initialize the connection correctly. The connection to the database
+{\it is} open and can be used via the direct SQL commands, if this
+function returns true. Other functions which depend on the
+\helpref{wxDb::Open}{wxdbopen} to have completed correctly may not function
+as expected. The return result from \helpref{wxDb::Open}{wxdbopen} is the
+only way to know if complete initialization of this wxDb connection was
+successful or not. See \helpref{wxDb::Open}{wxdbopen} for more details on
+partial failures to open a connection instance.
+
+\membersection{wxDb::LogError}\label{wxdblogerror}
+
+\func{void}{LogError}{\param{const wxString \&}{errMsg} \param{const wxString \&}{SQLState=""}}
+
+\docparam{errMsg}{Free-form text to display describing the error/text to be logged.}
+\docparam{SQLState}{{\it OPTIONAL.} Native SQL state error. Default is 0.}
+
+\wxheading{Remarks}
+
+Calling this function will enter a log message in the error list maintained
+for the database connection. This log message is free form and can be
+anything the programmer wants to enter in the error list.
+
+If SQL logging is turned on, the call to this function will also log the
+text into the SQL log file.
+
+\wxheading{See also}
+
+\helpref{wxDb::WriteSqlLog}{wxdbwritesqllog}
+
+\membersection{wxDb::ModifyColumn}\label{wxdbmodifycolumn}
+
+\func{void}{ModifyColumn}{\param{const wxString \&}{tableName} \param{const wxString \&}{ColumnName}
+\param{int }{dataType} \param{ULONG }{columnLength=0} \param{const wxString \&}{optionalParam=""}}
+
+Used to change certain properties of a column such as the length, or whether a column
+allows NULLs or not.
+
+\docparam{tableName}{Name of the table that the column to be modified is in.}
+\docparam{columnName}{Name of the column to be modified. NOTE: Name of column cannot
+be changed with this function.}
+\docparam{dataType}{Any one of DB\_DATA\_TYPE\_VARCHAR, DB\_DATA\_TYPE\_INTEGER,
+DB\_DATA\_TYPE\_FLOAT, DB\_DATA\_TYPE\_DATE.}
+\docparam{columnLength}{New size of the column. Valid only for DB\_DATA\_TYPE\_VARCHAR
+dataType fields. Default is 0.}
+\docparam{optionalParam}{Default is "".}
+
+\wxheading{Remarks}
+
+Cannot be used to modify the precision of a numeric column, therefore 'columnLength'
+is ignored unless the dataType is DB\_DATA\_TYPE\_VARCHAR.
+
+Some datasources do not allow certain properties of a column to be changed if any rows
+currently have data stored in that column. Those datasources that do allow columns
+to be changed with data in the rows many handle truncation and/or expansion in
+different ways. Please refer to the reference material for the datasource being
+used for behavioral descriptions.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ ok = pDb->ModifyColumn("CONTACTS", "ADDRESS2",
+ DB_, colDefs[j].SzDataObj,
+ wxT("NOT NULL"));
+\end{verbatim}
+
+
+\membersection{wxDb::Open}\label{wxdbopen}
+
+\func{bool}{Open}{\param{const wxString \&}{Dsn}, \param{const wxString \&}{Uid},
+\param{const wxString \&}{AuthStr}, \param{bool }{failOnDataTypeUnsupported}}
+
+\func{bool}{Open}{\param{const wxString \&}{inConnectStr},
+\param{bool }{failOnDataTypeUnsupported}}
+
+\func{bool}{Open}{\param{wxDbConnectInf *}{dbConnectInf},
+\param{bool }{failOnDataTypeUnsupported}}
+
+\func{bool}{Open}{\param{wxDb *}{copyDb}}
+
+Opens a connection to the datasource, sets certain behaviors of the datasource
+to confirm to the accepted behaviors (e.g. cursor position maintained on
+commits), and queries the datasource for its representations of the basic
+datatypes to determine the form in which the data going to/from columns in
+the data tables are to be handled.
+
+The second form of this function, which accepts a "wxDb *" as a parameter,
+can be used to avoid the overhead (execution time, database load, network
+traffic) which are needed to determine the data types and representations
+of data that are necessary for cross-datasource support by these classes.
+
+Normally the first form of the wxDb::Open() function will open the connection
+and then send a series of queries to the datasource asking it for its
+representation of data types, and all the features it supports. If one
+connection to the datasource has already been made previously, the information
+gathered when that connection was created can just be copied to any new
+connections to the same datasource by passing a pointer to the first
+connection in as a parameter to the wxDb::Open() function. Note that this
+new connection created from the first connections information will use the
+same Dsn/Uid/AuthStr as the first connection used.
+
+\wxheading{Parameters}
+
+\docparam{Dsn}{datasource name. The name of the ODBC datasource as
+assigned when the datasource is initially set up through the ODBC data
+source manager.}
+\docparam{Uid}{User ID. The name (ID) of the user you wish to connect as
+to the datasource. The user name (ID) determines what objects you
+have access to in the datasource and what datasource privileges you have.
+Privileges include being able to create new objects, update objects, delete
+objects and so on. Users and privileges are normally administered by the
+database administrator.}
+\docparam{AuthStr}{The password associated with the Uid.}
+\docparam{failOnDataTypeUnsupporte}{As part of connecting to a database, the
+wxDb::Open() function will query the database to find out the native types
+that it supports. With some databases, some data types may not be supported,
+or not sufficiently supported, for use with the wxODBC classes. Normally
+a program should fail in this case, so as not to try to use a data type
+that is not supported. This parameter allows the programmer to override the
+failure if they wish and continue on using the connection.}
+\docparam{dbConnectInf}{Contains a DSN, Uid, Password, or a connection string
+to be used in opening a new connection to the database. If a connection
+string is present, then the connection string will be used. If there is no
+connection string present, then the DSN, Uid, and Password are used.}
+\docparam{inConnectStr}{A valid ODBC connection string used to connect to a
+database}
+\docparam{copyDb}{Already completely configured and opened datasource
+connection from which all Dsn, Uid, AuthStr, connection string, and data
+typing information is to be copied from for use by this datasource
+connection. If 'copyDb' used a connection string to create its connection
+originally, then the connection being made by this call to wxDb::Open() will
+use that same connection string.}
+
+\wxheading{Remarks}
+
+After a wxDb instance is created, it must then be opened. When opening a
+datasource, there must be three pieces of information passed. The data
+source name, user name (ID) and the password for the user. No database
+activity on the datasource can be performed until the connection is opened.
+This is normally done at program startup and the datasource remains
+open for the duration of the program/module run.
+
+It is possible to have connections to multiple datasources open at the same
+time to support distributed database connections by having separate instances
+of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.
+
+If this function returns a value of false, it does not necessarily mean that
+the connection to the datasource was not opened. It may mean that some
+portion of the initialization of the connection failed (such as a datatype not
+being able to be determined how the datasource represents it). To determine
+if the connection to the database failed, use the \helpref{wxDb::IsOpen}{wxdbisopen}
+function after receiving a false result back from this function to determine if
+the connection was opened or not. If this function returns false, but \helpref{wxDb::IsOpen}{wxdbisopen}
+returns true, then direct SQL commands may be passed to the database
+connection and can be successfully executed, but use of the datatypes (such as
+by a wxDbTable instance) that are normally determined during open will not be
+possible.
+
+\normalbox{The {\it Dsn}, {\it Uid}, and {\it AuthStr} string pointers that are passed in
+are copied. NOT the strings themselves, only the pointers. The calling routine
+must maintain the memory for these three strings for the life of the wxDb instance.}
+
+\wxheading{Example}
+
+\begin{verbatim}
+ wxDb sampleDB(DbConnectInf.GetHenv());
+ if (!sampleDB.Open("Oracle 7.1 HP/UX", "gtasker", "myPassword"))
+ {
+ if (sampleDb.IsOpen())
+ {
+ // Connection is open, but the initialization of
+ // datatypes and parameter settings failed
+ }
+ else
+ {
+ // Error opening datasource
+ }
+ }
+\end{verbatim}
+
+\membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}
+
+\func{bool}{RollbackTrans}{\void}
+
+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.
+
+\wxheading{Remarks}
+
+Transactions begin implicitly as soon as you make a change to the database. The
+transaction continues until either a commit or rollback is executed. Calling
+wxDb::RollbackTrans() will result in ALL changes done using this database
+connection that have not already been committed to be "undone" back to the last
+commit/rollback that was successfully executed.
+
+\normalbox{Calling this member function rolls back ALL open (uncommitted)
+transactions on this ODBC connection, including all wxDbTable instances that
+use this connection.}
+
+\wxheading{See also}
+
+\helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors
+
+\membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
+
+\func{void}{SetDebugErrorMessages}{\param{bool }{state}}
+
+\docparam{state}{Either true (debug messages are logged) or false (debug
+messages are not logged).}
+
+\wxheading{Remarks}
+
+Turns on/off debug error messages from the ODBC class library. When
+this function is passed true, errors are reported to the user/logged automatically
+in a text or pop-up dialog when an ODBC error occurs. When passed false,
+errors are silently handled.
+
+When compiled in release mode (FINAL=1), this setting has no affect.
+
+\wxheading{See also}
+
+\helpref{wxDb constructor}{wxdbctor}
+
+\membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
+
+\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxString \&}{filename = SQL\_LOG\_FILENAME}, \param{bool }{ append = false}}
+
+\wxheading{Parameters}
+
+\docparam{state}{Either sqlLogOFF or sqlLogON (see \helpref{enum wxDbSqlLogState}{wxdbcolfor}). Turns logging of SQL commands sent to the datasource OFF or ON.}
+\docparam{filename}{{\it OPTIONAL}. Name of the file to which the log text is to be written. Default is SQL\_LOG\_FILENAME.}
+\docparam{append}{{\it OPTIONAL}. Whether the file is appended to or overwritten. Default is false.}
+
+\wxheading{Remarks}
+
+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.
+
+When called with {\it sqlLogOFF}, the logging file is closed, and any calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} are ignored.
+
+\membersection{wxDb::SQLColumnName}\label{wxdbsqlcolumnname}
+
+\func{const wxString}{SQLColumnName}{\param{const char *}{ colName}}
+
+Returns the column name in a form ready for use in SQL statements.
+In most cases, the column name is returned verbatim. But some databases
+(e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which
+must be specially quoted. For example, if the datasource allows spaces
+in the column name, the returned string will have the correct enclosing
+marks around the name to allow it to be properly included in a SQL statement
+for the DBMS that is currently connected to with this connection.
+
+\wxheading{Parameters}
+
+\docparam{colName}{Native name of the column in the table that is to be
+evaluated to determine if any special quoting marks needed to be added to it
+before including the column name in a SQL statement}
+
+\wxheading{See also}
+
+\helpref{wxDb::SQLTableName}{wxdbsqltablename}
+
+\membersection{wxDb::SQLTableName}\label{wxdbsqltablename}
+
+\func{const wxString}{SQLTableName}{\param{const char *}{ tableName}}
+
+Returns the table name in a form ready for use in SQL statements.
+In most cases, the table name is returned verbatim. But some databases
+(e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which
+must be specially quoted. For example, if the datasource allows spaces
+in the table name, the returned string will have the correct enclosing
+marks around the name to allow it to be properly included in a SQL statement
+for the data source that is currently connected to with this connection.
+
+\wxheading{Parameters}
+
+\docparam{tableName}{Native name of the table that is to be evaluated to
+determine if any special quoting marks needed to be added to it
+before including the table name in a SQL statement}
+
+\wxheading{See also}
+
+\helpref{wxDb::SQLColumnName}{wxdbsqlcolumnname}
+
+\membersection{wxDb::TableExists}\label{wxdbtableexists}
+
+\func{bool}{TableExists}{\param{const wxString \&}{tableName}, \param{const wxChar *}{userID=NULL}, \param{const wxString \&}{path=""}}
+
+Checks the ODBC datasource for the existence of a table. If a {\it userID}
+is specified, then the table must be accessible by that user (user must have
+at least minimal privileges to the table).
+
+\wxheading{Parameters}
+
+\docparam{tableName}{Name of the table to check for the existence of.}
+\docparam{userID}{Owner of the table (also referred to as schema). 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:}
+
+\begin{verbatim}
+ userID == NULL ... UserID is ignored (DEFAULT)
+ userID == "" ... UserID set equal to 'this->uid'
+ userID != "" ... UserID set equal to 'userID'
+\end{verbatim}
+
+\wxheading{Remarks}
+
+{\it tableName} may refer to a table, view, alias or synonym.
+
+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.
+
+\wxheading{See also}
+
+\helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
+
+\membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}
+
+\func{bool}{TablePrivileges}{\param{const wxString \&}{tableName}, \param{const wxString \&}{priv},
+\param{const wxChar *}{userID=NULL}, \param{const wxChar *}{schema=NULL},
+\param{const wxString \&}{path=""}}
+
+Checks the ODBC datasource for the existence of a table. If a {\it userID}
+is specified, then the table must be accessible by that user (user must have
+at least minimal privileges to the table).
+
+\wxheading{Parameters}
+
+\docparam{tableName}{Name of the table on which to check privileges.
+{\it tableName} may refer to a table, view, alias or synonym.}
+\docparam{priv}{The table privilege being evaluated. May be one of the
+following (or a datasource specific privilege):}
+
+\begin{verbatim}
+ SELECT : The connected user is permitted to retrieve data for
+ one or more columns of the table.
+
+ INSERT : The connected user is permitted to insert new rows
+ containing data for one or more columns into the
+ table.
+
+ UPDATE : The connected user is permitted to update the data in
+ one or more columns of the table.
+
+ DELETE : The connected user is permitted to delete rows of
+ data from the table.
+
+ REFERENCES : Is the connected user permitted to refer to one or
+ more columns of the table within a constraint (for
+ example, a unique, referential, or table check
+ constraint).
+\end{verbatim}
+
+\docparam{userID}{{\it OPTIONAL.} User for which to determine if the privilege
+specified to be checked is granted or not. Default is "".
+{\it userID} is evaluated as follows:}
+
+\begin{verbatim}
+ userID == NULL ... NOT ALLOWED!
+ userID == "" ... UserID set equal to 'this->uid'
+ userID != "" ... UserID set equal to 'userID'
+\end{verbatim}
+
+\docparam{schema}{{\it OPTIONAL.} Owner 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. Specifying the table owner makes determination of the
+users privileges MUCH faster. Default is NULL. {\it userID} is
+evaluated as follows:}
+
+\begin{verbatim}
+ schema == NULL ... Any owner (DEFAULT)
+ schema == "" ... Owned by 'this->uid'
+ schema != "" ... Owned by userID specified in 'schema'
+\end{verbatim}
+
+\docparam{path}{{\it OPTIONAL.} Path to the table. Default is "".
+Currently unused.}
+
+\wxheading{Remarks}
+
+The scope of privilege allowed to the connected user by a given table
+privilege is datasource dependent.
+
+For example, the privilege UPDATE might allow the connected user to update
+all columns in a table on one datasource, but only those columns for
+which the grantor (the user that granted the connected user) has the UPDATE
+privilege on another datasource.
+
+Looking up a user's privileges to a table can be time consuming depending on the
+datasource and ODBC driver. This time can be minimized by passing a {\it schema}
+as a parameter. With some datasources/drivers, the difference can be several
+seconds of time difference.
+
+
+\membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}
+
+\func{int }{TranslateSqlState}{\param{const wxString \&}{SQLState}}
+
+Converts an ODBC sqlstate to an internal error code.
+
+\wxheading{Parameters}
+
+\docparam{SQLState}{State to be converted.}
+
+\wxheading{Return value}
+
+Returns the internal class DB\_ERR code. See \helpref{wxDb::DB\_STATUS}{wxdb} definition.
+
+\membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
+
+\func{bool}{WriteSqlLog}{\param{const wxString \&}{logMsg}}
+
+\wxheading{Parameters}
+
+\docparam{logMsg}{Free form string to be written to the log file.}
+
+\wxheading{Remarks}
+
+Very useful debugging tool that may be turned on/off during run time (see
+(see \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging} for details on
+turning logging on/off). The passed in string {\it logMsg} will be written to
+a log file if SQL logging is turned on.
+
+\wxheading{Return value}
+
+If SQL logging is off when a call to WriteSqlLog() is made, or there is a
+failure to write the log message to the log file, the function returns
+false without performing the requested log, otherwise true is returned.
+
+\wxheading{See also}
+
+\helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
+
+\section{\class{wxDbColDataPtr}}\label{wxdbcoldataptr}
+
+Pointer to dynamic column definitions for use with a wxDbTable instance.
+Currently there are no member functions for this class.
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\begin{verbatim}
+ void *PtrDataObj;
+ int SzDataObj;
+ SWORD SqlCtype;
+\end{verbatim}
+
+\section{\class{wxDbColDef}}\label{wxdbcoldef}
+
+This class is used to hold information about the columns bound to an
+instance of a wxDbTable object.
+
+Each instance of this class describes one column in the wxDbTable
+object. When calling the \helpref{wxDb constructor}{wxdbctor}, a
+parameter passed in indicates the number of columns that will be defined for
+the wxDbTable object. The constructor uses this information to allocate
+adequate memory for all of the column descriptions in your wxDbTable object.
+Private member wxDbTable::colDefs is a pointer to this chunk of memory
+maintained by the wxDbTable class (and can be retrieved using the
+\helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs} function).
+To access the nth column definition of your wxDbTable object, just reference
+wxDbColDefs element [n - 1].
+
+Typically, \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} is used to
+populate an array of these data structures for the wxDbTable instance.
+
+Currently there are no accessor functions for this class, so all members are
+public.
+
+\begin{verbatim}
+ wxChar ColName[DB_MAX_COLUMN_NAME_LEN+1]; // Column Name
+ int DbDataType; - Logical Data Type;
+ e.g. DB_DATA_TYPE_INTEGER
+ SWORD SqlCtype; - C data type; e.g. SQL_C_LONG
+ void *PtrDataObj; - Address of the data object
+ int SzDataObj; - Size, in bytes, of the data object
+ bool KeyField; - Is column part of the PRIMARY KEY for the
+ table? -- Date fields should NOT be
+ KeyFields
+ bool Updateable; - Column is updateable?
+ bool InsertAllowed; - Column included in INSERT statements?
+ bool DerivedCol; - Column is a derived value?
+ SDWORD CbValue; - !!!Internal use only!!!
+ bool Null; - NOT FULLY IMPLEMENTED
+ Allows NULL values in Inserts and Updates
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{database classes overview}{odbcoverview},
+\helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs}, \helpref{wxDb constructor}{wxdbctor}
+
+\wxheading{Include files}
+
+<wx/db.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbColDef::Initialize}\label{wxdbcoldefinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+\section{\class{wxDbColFor}}\label{wxdbcolfor}
+
+Beginning support for handling international formatting specifically on dates
+and floats.
+
+\begin{verbatim}
+ wxString s_Field; // Formatted String for Output
+ wxString s_Format[7]; // Formatted Objects - TIMESTAMP has
+ the biggest (7)
+ wxString s_Amount[7]; // Formatted Objects - amount of
+ things that can be formatted
+ int i_Amount[7]; // Formatted Objects -
+ TT MM YYYY HH MM SS m
+ int i_Nation; // 0 = timestamp
+ 1 = EU
+ 2 = UK
+ 3 = International
+ 4 = US
+ int i_dbDataType; // conversion of the 'sqlDataType'
+ to the generic data type used by
+ these classes
+ SWORD i_sqlDataType;
+\end{verbatim}
+
+The constructor for this class initializes all the values to zero or NULL.
+
+The destructor does nothing at this time.
+
+Only one function is provided with this class currently.
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\wxheading{Include files}
+
+<wx/db.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbColFor::Format}\label{wxdbcolforformat}
+
+\func{int }{Format}{\param{int }{Nation}, \param{int }{dbDataType},
+\param{SWORD }{sqlDataType}, \param{short }{columnSize},
+\param{short }{decimalDigits}}\label{wxdbcolforformat}
+
+Work in progress, and should be inter-related with wxLocale eventually.
+
+\membersection{wxDbColFor::Initialize}\label{wxdbcolforinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+\section{\class{wxDbColInf}}\label{wxdbcolinf}
+
+Used with the \helpref{wxDb::GetColumns}{wxdbgetcolumns} functions for obtaining all retrievable information about a column's definition.
+
+\begin{verbatim}
+ wxChar catalog[128+1];
+ wxChar schema[128+1];
+ wxChar tableName[DB_MAX_TABLE_NAME_LEN+1];
+ wxChar colName[DB_MAX_COLUMN_NAME_LEN+1];
+ SWORD sqlDataType;
+ wxChar typeName[128+1];
+ SWORD columnSize;
+ SWORD bufferLength;
+ short decimalDigits;
+ short numPrecRadix;
+ short nullable;
+ wxChar remarks[254+1];
+ int dbDataType; // conversion of the 'sqlDataType'
+ // to the generic data type used by
+ // these classes
+ int PkCol; // Primary key column
+ 0 = No
+ 1 = First Key
+ 2 = Second Key, etc...
+ wxChar PkTableName[DB_MAX_TABLE_NAME_LEN+1];
+ // Tables that use this PKey as a FKey
+ int FkCol; // Foreign key column
+ 0 = No
+ 1 = First Key
+ 2 = Second Key, etc...
+ wxChar FkTableName[DB_MAX_TABLE_NAME_LEN+1];
+ // Foreign key table name
+ wxDbColFor *pColFor; // How should this column be formatted
+\end{verbatim}
+
+The constructor for this class initializes all the values to zero, "", or NULL.
+
+The destructor for this class takes care of deleting the pColFor member if
+it is non-NULL.
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\wxheading{Include files}
+
+<wx/db.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbColInf::Initialize}\label{wxdbcolinfinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+\section{\class{wxDbConnectInf}}\label{wxdbconnectinf}
+
+This class is used for holding the data necessary for connecting to the ODBC
+datasource. That information includes: SQL environment handle, datasource
+name, user ID, password and default directory path (used with dBase). Other
+optional fields held in this class are and file type, both for future
+functions planned to be added for creating/manipulating datasource definitions.
+
+\membersection{wxDbConnectInf::wxDbConnectInf}\label{wxdbconnectinfctor}
+
+\func{}{wxDbConnectInf}{\void}
+
+Default constructor.
+
+\func{}{wxDbConnectInf}{\param{HENV }{henv}, \param{const wxString \&}{dsn},
+\param{const wxString \&}{userID=""}, \param{const wxString \&}{password},
+\param{const wxString \&}{defaultDir=""}, \param{const wxString \&}{description=""},
+\param{const wxString \&}{fileType=""}}
+
+Constructor which allows initial settings of all the classes member variables.
+
+See the special note below on the henv parameter for forcing this constructor
+to create a SQL environment handle automatically, rather than needing to pass
+one in to the function.
+
+\wxheading{Parameters}
+
+\docparam{henv}{Environment handle used for this connection. See\rtfsp
+\helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv} for how to create
+an SQL environment handle. NOTE: Passing in a NULL for this parameter will
+inform the constructor that it should create its own SQL environment handle.
+If NULL is passed for this parameter, the constructor will call\rtfsp
+\helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv} internally. A
+flag is set internally also to indicate that the HENV was created by the
+constructor so that when the default class destructor is called, the
+destructor will call \helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}\rtfsp
+to free the environment handle automatically.}
+\docparam{dsn}{Name of the datasource to be used in creating wxDb instances
+for creating connection(s) to a datasource.}
+\docparam{userID}{{\it OPTIONAL} Many datasources allow (or even require)
+use of a username to determine privileges that connecting user is allowed
+to have when accessing the datasource or the data tables. Default is "".}
+\docparam{password}{{\it OPTIONAL} Password to be associated with the user
+ID specified in 'userID'. Default is "".}
+\docparam{defaultDir}{{\it OPTIONAL} Used for datasources which require the
+path to where the data file is stored to be specified. dBase is one example
+of the type of datasource which requires this information. Default is "".}
+\docparam{description}{{\it OPTIONAL} {\bf FUTURE USE} Default is "".}
+\docparam{fileType}{{\it OPTIONAL} {\bf FUTURE USE} Default is "".}
+
+\wxheading{Remarks}
+
+It is strongly recommended that programs use the longer form of the
+constructor and allow the constructor to create the SQL environment handle
+automatically, and manage the destruction of the handle.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ wxDbConnectInf *DbConnectInf;
+
+ DbConnectInf = new wxDbConnectInf(0,"MY_DSN", "MY_USER", "MY_PASSWORD");
+
+ ....the rest of the program
+
+ delete DbConnectInf;
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv},
+\helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}
+
+\membersection{wxDbConnectInf::\destruct{wxDbConnectInf}}\label{wxdbconnectinfdestr}
+
+\func{}{\destruct{wxDbConnectInf}}{}
+
+Handles the default destruction of the instance of the class. If the long form
+of the \helpref{wxDConnectInf}{wxdbconnectinf} was used, then this destructor
+also takes care of calling\rtfsp
+\helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv} to free the
+SQL environment handle.
+
+\membersection{wxDbConnectInf::AllocHenv}\label{wxdbconnectinfallochenv}
+
+\func{bool }{AllocHenv}{\void}
+
+Allocates a SQL environment handle that will be used to interface with
+an ODBC datasource.
+
+\wxheading{Remarks}
+
+This function can be automatically called by the long from of the
+\helpref{wxDbConnectInf}{wxdbconnectinf} constructor.
+
+\membersection{wxDbConnectInf::FreeHenv}\label{wxdbconnectinffreehenv}
+
+\func{void}{FreeHenv}{\void}
+
+Frees the SQL environment handle being managed by the instance of this class.
+
+\wxheading{Remarks}
+
+If the SQL environment handle was created using the long form of the\rtfsp
+\helpref{wxDbConnectInf}{wxdbconnectinf} constructor, then the flag indicating
+that the HENV should be destroyed when the classes destructor is called
+is reset to be false, so that any future handles created using the\rtfsp
+\helpref{wxDbConnectInf::AllocHenv}{wxdbconnectinfallochenv} function
+must be manually released with a call to this function.
+
+\membersection{wxDbConnectInf::Initialize}\label{wxdbconnectinfinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+\membersection{wxDbConnectInf::GetAuthStr}\label{wxdbconnectinfgetauthstr}
+
+\func{const wxChar *}{GetAuthStr}{\void}
+
+Accessor function to return the password assigned for this class
+instance that will be used with the user ID.
+
+Synonymous with \helpref{wxDbConnectInf::GetPassword}{wxdbconnectinfgetpassword}
+
+\membersection{wxDbConnectInf::GetDefaultDir}\label{wxdbconnectinfgetdefaultdir}
+
+\func{const wxChar *}{GetDefaultDir}{\void}
+
+Accessor function to return the default directory in which the datasource's data
+table is stored. This directory is only used for file based datasources like
+dBase. MS-Access does not require this to be set, as the path is set in the
+ODBC Administrator for MS-Access.
+
+\membersection{wxDbConnectInf::GetDescription}\label{wxdbconnectinfgetdescription}
+
+\func{const wxChar *}{GetDescription}{\void}
+
+Accessor function to return the description assigned for this class
+instance.
+
+NOTE: Description is a FUTURE USE item and is unused currently.
+
+\membersection{wxDbConnectInf::GetDsn}\label{wxdbconnectinfgetdsn}
+
+\func{const wxChar *}{GetDsn}{\void}
+
+Accessor function to return the datasource name assigned for this class
+instance.
+
+\membersection{wxDbConnectInf::GetFileType}\label{wxdbconnectinfgetfiletype}
+
+\func{const wxChar *}{GetFileType}{\void}
+
+Accessor function to return the filetype of the ODBC datasource assigned for
+this class instance.
+
+NOTE: FileType is a FUTURE USE item and is unused currently.
+
+\membersection{wxDbConnectInf::GetHenv}\label{wxdbconnectinfgethenv}
+
+\func{const HENV}{GetHenv}{\void}
+
+Accessor function to return the SQL environment handle being managed
+by this class instance.
+
+\membersection{wxDbConnectInf::GetPassword}\label{wxdbconnectinfgetpassword}
+
+\func{const wxChar *}{GetPassword}{\void}
+
+Accessor function to return the password assigned for this class
+instance that will be used with the user ID.
+
+Synonymous with \helpref{wxDbConnectInf::GetAuthStr}{wxdbconnectinfgetauthstr}
+
+\membersection{wxDbConnectInf::GetUid}\label{wxdbconnectinfgetuid}
+
+\func{const wxChar *}{GetUid}{\void}
+
+Accessor function to return the user ID assigned for this class
+instance.
+
+\membersection{wxDbConnectInf::GetUserID}\label{wxdbconnectinfgetuserid}
+
+\func{const wxChar *}{GetUserID}{\void}
+
+Accessor function to return the user ID assigned for this class
+instance.
+
+\membersection{wxDbConnectInf::SetAuthStr}\label{wxdbconnectinfsetauthstr}
+
+\func{\void}{SetAuthStr}{const wxString \&authstr}
+
+Accessor function to assign the password for this class
+instance that will be used with the user ID.
+
+Synonymous with \helpref{wxDbConnectInf::SetPassword}{wxdbconnectinfsetpassword}
+
+\membersection{wxDbConnectInf::SetDefaultDir}\label{wxdbconnectinfsetdefaultdir}
+
+\func{\void}{SetDefaultDir}{const wxString \&defDir}
+
+Accessor function to assign the default directory in which the datasource's data
+table is stored. This directory is only used for file based datasources like
+dBase. MS-Access does not require this to be set, as the path is set in the
+ODBC Administrator for MS-Access.
+
+\membersection{wxDbConnectInf::SetDescription}\label{wxdbconnectinfsetdescription}
+
+\func{\void}{SetDescription}{const wxString \&desc}
+
+Accessor function to assign the description assigned for this class
+instance.
+
+NOTE: Description is a FUTURE USE item and is unused currently.
+
+\membersection{wxDbConnectInf::SetDsn}\label{wxdbconnectinfsetdsn}
+
+\func{\void}{SetDsn}{const wxString \&dsn}
+
+Accessor function to assign the datasource name for this class instance.
+
+\membersection{wxDbConnectInf::SetFileType}\label{wxdbconnectinfsetfiletype}
+
+\func{\void}{SetFileType}{const wxString \&}
+
+Accessor function to return the filetype of the ODBC datasource assigned for
+this class instance.
+
+NOTE: FileType is a FUTURE USE item and is unused currently.
+
+\membersection{wxDbConnectInf::SetHenv}\label{wxdbconnectinfsethenv}
+
+\func{void}{SetHenv}{\param{const HENV }{henv}}
+
+Accessor function to set the SQL environment handle for this class instance.
+
+\membersection{wxDbConnectInf::SetPassword}\label{wxdbconnectinfsetpassword}
+
+\func{\void}{SetPassword}{const wxString \&password}
+
+Accessor function to assign the password for this class
+instance that will be used with the user ID.
+
+Synonymous with \helpref{wxDbConnectInf::SetAuthStr}{wxdbconnectinfsetauthstr}
+
+\membersection{wxDbConnectInf::SetUid}\label{wxdbconnectinfsetuid}
+
+\func{\void}{SetUid}{const wxString \&uid}
+
+Accessor function to set the user ID for this class instance.
+
+\membersection{wxDbConnectInf::SetUserID}\label{wxdbconnectinfsetuserid}
+
+\func{\void}{SetUserID}{const wxString \&userID}
+
+Accessor function to assign the user ID for this class instance.
+
+\section{\class{wxDbIdxDef}}\label{wxdbidxdef}
+
+Used in creation of non-primary indexes. Currently there are no member
+functions for this class.
+
+\begin{verbatim}
+ wxChar ColName[DB_MAX_COLUMN_NAME_LEN+1]
+ // Name of column
+ bool Ascending // Is index maintained in
+ ASCENDING sequence?
+\end{verbatim}
+
+There are no constructors/destructors as of this time, and no member functions.
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+
+\wxheading{Include files}
+
+<wx/db.h>
+
+\section{\class{wxDbInf}}\label{wxdbinf}
+
+Contains information regarding the database connection (datasource name,
+number of tables, etc). A pointer to a wxDbTableInf is included in this
+class so a program can create a wxDbTableInf array instance to maintain all
+information about all tables in the datasource to have all the datasource's
+information in one memory structure.
+
+Primarily, this class is used internally by the wxWidgets ODBC classes.
+
+\begin{verbatim}
+ wxChar catalog[128+1];
+ wxChar schema[128+1]; // typically means owner of table(s)
+ int numTables; // How many tables does this
+ datasource have
+ wxDbTableInf *pTableInf; // Equals a new
+ wxDbTableInf[numTables];
+\end{verbatim}
+
+The constructor for this class initializes all the values to zero, "", or NULL.
+
+The destructor for this class takes care of deleting the pTableInf member if
+it is non-NULL.
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\wxheading{Include files}
+
+<wx/db.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbInf::Initialize}\label{wxdbinfinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+\section{\class{wxDbTable}}\label{wxdbtable}
+
+A wxDbTable instance provides re-usable access to rows of data in
+a table contained within the associated ODBC datasource
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\wxheading{Include files}
+
+<wx/dbtable.h>\\
+<wx/db.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+\wxheading{Helper classes and data structures}
+
+The following classes and structs are defined in dbtable.cpp/.h for use
+with the wxDbTable class.
+
+\begin{itemize}\itemsep=0pt
+\item \helpref{wxDbColDef}{wxdbcoldef}
+\item \helpref{wxDbColDataPtr}{wxdbcoldataptr}
+\item \helpref{wxDbIdxDef}{wxdbidxdef}
+\end{itemize}
+
+\wxheading{Constants}
+
+\begin{verbatim}
+ wxDB_DEFAULT_CURSOR Primary cursor normally used for cursor based
+ operations.
+
+ wxDB_QUERY_ONLY Used to indicate whether a table that is opened
+ is for query only, or if insert/update/deletes
+ will be performed on the table. Less overhead
+ (cursors and memory) are allocated for query
+ only tables, plus read access times are faster
+ with some datasources.
+
+ wxDB_ROWID_LEN [Oracle only] - Used when CanUpdateByRowID()
+ is true. Optimizes updates so they are faster
+ by updating on the Oracle-specific ROWID column
+ rather than some other index.
+
+
+ wxDB_DISABLE_VIEW Use to indicate when a database view should not
+ be if a table is normally set up to use a view.
+ [Currently unsupported.]
+
+\end{verbatim}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbTable::wxDbTable}\label{wxdbtableconstr}
+
+\func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const wxString \&}{tblName},
+ \param{const UWORD }{numColumns}, \param{const wxString \&}{qryTblName = ""},
+ \param{bool }{qryOnly = !wxDB\_QUERY\_ONLY}, \param{const wxString \&}{tblPath = ""}}
+
+Default constructor.
+
+\wxheading{Parameters}
+
+\docparam{pwxDb}{Pointer to the wxDb instance to be used by this wxDbTable
+instance.}
+\docparam{tblName}{The name of the table in the RDBMS.}
+\docparam{numColumns}{The number of columns in the table. (Do NOT include the ROWID
+column in the count if using Oracle).}
+\docparam{qryTblName}{{\it OPTIONAL}. The name of the table or view to base
+your queries on. This argument allows you to specify a table/view other than
+the base table for this object to base your queries on. This allows you to
+query on a view for example, but all of the INSERT, UPDATE and DELETES will
+still be performed on the base table for this wxDbTable object. Basing your
+queries on a view can provide a substantial performance increase in cases where
+your queries involve many tables with multiple joins. Default is "".}
+\docparam{qryOnly}{{\it OPTIONAL}. Indicates whether the table will be
+accessible for query purposes only, or should the table create the necessary
+cursors to be able to insert, update, and delete data from the table.
+Default is !wxDB\_QUERY\_ONLY.}
+\docparam{tblPath}{{\it OPTIONAL}. Some datasources (such as dBase)
+require a path to where the table is stored on the system. Default is "".}
+
+\membersection{wxDbTable::wxDbTable}\label{wxdbtabledestr}
+
+\func{virtual}{\destruct{wxDbTable}}{}
+
+Virtual default destructor.
+
+\membersection{wxDbTable::BuildDeleteStmt}\label{wxdbtablebuilddeletestmt}
+
+\func{void}{BuildDeleteStmt}{\param{wxString \&}{pSqlStmt},
+\param{int }{typeOfDel}, \param{const wxString \&}{pWhereClause=""}}
+
+Constructs the full SQL statement that can be used to delete all rows matching
+the criteria in the pWhereClause.
+
+\wxheading{Parameters}
+
+\docparam{pSqlStmt}{Pointer to buffer for the SQL statement retrieved. To be
+sure you have adequate space allocated for the SQL statement, allocate
+DB\_MAX\_STATEMENT\_LEN bytes.}
+\docparam{typeOfDel}{The type of delete statement being performed. Can be one
+of three values: DB\_DEL\_KEYFIELDS, DB\_DEL\_WHERE or DB\_DEL\_MATCHING}
+\docparam{pWhereClause}{{\it OPTIONAL}. If the typeOfDel is DB\_DEL\_WHERE,
+then you must also pass in a SQL WHERE clause in this argument. Default
+is "".}
+
+\wxheading{Remarks}
+
+This member function constructs a SQL DELETE statement. This can be used for
+debugging purposes if you are having problems executing your SQL statement.
+
+WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
+
+\membersection{wxDbTable::BuildSelectStmt}\label{wxdbtablebuildselectstmt}
+
+\func{void}{BuildSelectStmt}{\param{wxString \&}{pSqlStmt},
+\param{int }{typeOfSelect}, \param{bool }{distinct}}
+
+Constructs the full SQL statement that can be used to select all rows matching
+the criteria in the pWhereClause. This function is called internally in the
+wxDbTable class whenever the function \helpref{wxDbTable::Query}{wxdbtablequery}
+is called.
+
+NOTE: Only the columns specified in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
+statements are included in the list of columns returned by the SQL statement
+created by a call to this function.
+
+\wxheading{Parameters}
+
+\docparam{pSqlStmt}{Pointer to storage for the SQL statement retrieved. To be
+sure you have adequate space allocated for the SQL statement, allocate
+DB\_MAX\_STATEMENT\_LEN bytes.}
+\docparam{typeOfSelect}{The type of select statement being performed. Can be
+one of four values: DB\_SELECT\_KEYFIELDS, DB\_SELECT\_WHERE, DB\_SELECT\_MATCHING
+or DB\_SELECT\_STATEMENT.}
+\docparam{distinct}{Whether to select distinct records only.}
+
+\wxheading{Remarks}
+
+This member function constructs a SQL SELECT statement. This can be used for
+debugging purposes if you are having problems executing your SQL statement.
+
+WHERE and FROM clauses specified using
+\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
+
+\membersection{wxDbTable::BuildUpdateStmt}\label{wxdbtablebuildupdatestmt}
+
+\func{void}{BuildUpdateStmt}{\param{wxString \&}{pSqlStmt}, \param{int }{typeOfUpd},
+\param{const wxString \&}{pWhereClause=""}}
+
+Constructs the full SQL statement that can be used to update all rows matching
+the criteria in the pWhereClause.
+
+If typeOfUpdate is DB\_UPD\_KEYFIELDS, then the current values in the bound columns
+are used to determine which row(s) in the table are to be updated. The
+exception to this is when a datasource supports ROW IDs (Oracle). The ROW ID
+column is used for efficiency purposes when available.
+
+NOTE: Only the columns specified in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
+statements are included in the list of columns updated by the SQL statement
+created by a call to this function. Any column definitions that were defined
+as being non-updateable will be excluded from the SQL UPDATE statement created
+by this function.
+
+\wxheading{Parameters}
+
+\docparam{pSqlStmt}{Pointer to storage for the SQL statement retrieved. To be
+sure you have adequate space allocated for the SQL statement, allocate
+DB\_MAX\_STATEMENT\_LEN bytes.}
+\docparam{typeOfUpdate}{The type of update statement being performed. Can be one
+of two values: DB\_UPD\_KEYFIELDS or DB\_UPD\_WHERE.}
+\docparam{pWhereClause}{{\it OPTIONAL}. If the typeOfUpdate is DB\_UPD\_WHERE,
+then you must also pass in a SQL WHERE clause in this argument. Default is "".}
+
+\wxheading{Remarks}
+
+This member function allows you to see what the SQL UPDATE statement looks like
+that the ODBC class library builds. This can be used for debugging purposes if
+you are having problems executing your SQL statement.
+
+WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
+
+
+\membersection{wxDbTable::BuildWhereClause}\label{wxdbtablebuildwhereclause}
+
+\func{void}{BuildWhereClause}{\param{wxString \&}{pWhereClause},
+\param{int }{typeOfWhere}, \param{const wxString \&}{qualTableName=""},
+\param{bool }{useLikeComparison=false}}
+
+Constructs the portion of a SQL statement which would follow the word 'WHERE'
+in a SQL statement to be passed to the datasource. The returned string
+does NOT include the word 'WHERE'.
+
+\wxheading{Parameters}
+
+\docparam{pWhereClause}{Pointer to storage for the SQL statement retrieved.
+To be sure you have adequate space allocated for the SQL statement, allocate
+DB\_MAX\_STATEMENT\_LEN bytes.}
+\docparam{typeOfWhere}{The type of where clause to generate. Can be one of
+two values: DB\_WHERE\_KEYFIELDS or DB\_WHERE\_MATCHING.}
+\docparam{qualTableName}{{\it OPTIONAL}. Prepended to all base table
+column names. For use when a FROM clause has been specified with the
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause},
+to clarify which table a column name reference belongs to. Default is "".}
+\docparam{useLikeComparison}{{\it OPTIONAL}. Should the constructed WHERE
+clause utilize the LIKE comparison operator. If false, then the '='
+operator is used. Default is false.}
+
+\wxheading{Remarks}
+
+This member function allows you to see what the SQL WHERE clause looks like
+that the ODBC class library builds. This can be used for debugging purposes
+if you are having problems executing your own SQL statements.
+
+If using 'typeOfWhere' set to DB\_WHERE\_MATCHING, any bound columns currently
+containing a NULL value are not included in the WHERE clause's list of
+columns to use in the comparison.
+
+
+\membersection{wxDbTable::CanSelectForUpdate}\label{wxdbtablecanselectforupdate}
+
+\func{bool}{CanSelectForUpdate}{\void}
+
+Use this function to determine if the datasource supports SELECT ... FOR UPDATE.
+When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement,
+all records {\it retrieved} (not just queried, but actually retrieved using
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}, etc) from the result set are
+locked.
+
+\wxheading{Remarks}
+
+Not all datasources support the "FOR UPDATE" clause, so you must use this
+member function to determine if the datasource currently connected to supports
+this behavior or not before trying to select using "FOR UPDATE".
+
+If the wxDbTable instance was created with the parameter wxDB\_QUERY\_ONLY, then
+this function will return false. For all known databases which do not support
+the FOR UPDATE clause, this function will return false also.
+
+\membersection{wxDbTable::CanUpdateByROWID}\label{wxdbtablecanupdatebyrowid}
+
+\func{bool}{CanUpdateByROWID}{\void}
+
+CURRENTLY ONLY POSSIBLE IF USING ORACLE.
+
+--- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV 1 2000 - gt
+
+Every Oracle table has a hidden column named ROWID. This is a pointer to the
+physical location of the record in the datasource and allows for very fast
+updates and deletes. The key is to retrieve this ROWID during your query so
+it is available during an update or delete operation.
+
+Use of the ROWID feature is always handled by the class library except in the
+case of \helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}. Since
+you are passing in the SQL SELECT statement,
+it is up to you to include the ROWID column in your query. If you do not,
+the application will still work, but may not be as optimized. The ROWID is
+always the last column in the column list in your SQL SELECT statement.
+The ROWID is not a column in the normal sense and should not be considered
+part of the column definitions for the wxDbTable object.
+
+\wxheading{Remarks}
+
+The decision to include the ROWID in your SQL SELECT statement must be
+deferred until runtime since it depends on whether you are connected
+to an Oracle datasource or not.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ wxDbTable parts;
+ .....
+ if (parts.CanUpdateByROWID())
+ {
+ // Note that the ROWID column must always be the last column selected
+ sqlStmt = "SELECT PART_NUM, PART_DESC, ROWID" FROM PARTS";
+ }
+ else
+ sqlStmt = "SELECT PART_NUM, PART_DESC FROM PARTS";
+\end{verbatim}
+
+
+\membersection{wxDbTable::ClearMemberVar}\label{wxdbtableclearmembervar}
+
+\func{void}{ClearMemberVar}{\param{UWORD }{colNumber}, \param{bool }{setToNull=false}}
+
+Same as \helpref{wxDbTable::ClearMemberVars}{wxdbtableclearmembervars} except
+that this function clears only the specified column of its values, and
+optionally sets the column to be a NULL column.
+
+\docparam{colNumber}{Column number that is to be cleared. This number (between 0
+and (numColumns-1)) is the index of the column definition created using the
+\helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} function.}
+\docparam{setToNull}{{\it OPTIONAL}. Indicates whether the column should be
+flagged as being a NULL value stored in the bound memory variable. If true,
+then any value stored in the bound member variable is cleared. Default is
+false.}
+
+\membersection{wxDbTable::ClearMemberVars}\label{wxdbtableclearmembervars}
+
+\func{void}{ClearMemberVars}{\param{bool }{setToNull=false}}
+
+Initializes all bound columns of the wxDbTable instance to zero. In the case
+of a string, zero is copied to the first byte of the string.
+
+\docparam{setToNull}{{\it OPTIONAL}. Indicates whether all columns should be
+flagged as having a NULL value stored in the bound memory variable. If true,
+then any value stored in the bound member variable is cleared. Default is
+false.}
+
+\wxheading{Remarks}
+
+This is useful before calling functions such as
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
+\helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching} since these
+functions build their WHERE clauses from non-zero columns. To call either
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
+\helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching} use this sequence:
+
+\begin{verbatim}
+1) ClearMemberVars()
+2) Assign columns values you wish to match on
+3) Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
+\end{verbatim}
+
+\membersection{wxDbTable::CloseCursor}\label{wxdbtableclosecursor}
+
+\func{bool}{CloseCursor}{\param{HSTMT}{cursor}}
+
+Closes the specified cursor associated with the wxDbTable object.
+
+\wxheading{Parameters}
+
+\docparam{cursor}{The cursor to be closed.}
+
+\wxheading{Remarks}
+
+Typically handled internally by the ODBC class library, but may be used by the
+programmer if desired.
+
+\normalbox{DO NOT CLOSE THE wxDB\_DEFAULT\_CURSOR!}
+
+\membersection{wxDbTable::Count}\label{wxdbtablecount}
+
+\func{ULONG }{Count}{\param{const wxString \&}{args="*"}}
+
+Returns the number of records which would be in the result set using the
+current query parameters specified in the WHERE and FROM clauses.
+
+\wxheading{Parameters}
+
+\docparam{args}{{\it OPTIONAL}. This argument allows the use of the
+DISTINCT keyword against a column name to cause the returned count to
+only indicate the number of rows in the result set that have a unique
+value in the specified column. An example is shown below. Default is "*",
+meaning a count of the total number of rows matching is returned, regardless
+of uniqueness.}
+
+\wxheading{Remarks}
+
+This function can be called before or after an actual query to obtain the
+count of records in the result set. Count() uses its own cursor, so result
+set cursor positioning is not affected by calls to Count().
+
+WHERE and FROM clauses specified using
+\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} ARE used by
+this function.
+
+\wxheading{Example}
+
+\begin{verbatim}
+
+ USERS TABLE
+
+ FIRST_NAME LAST_NAME
+ ----------- ----------
+ John Doe
+ Richard Smith
+ Michael Jones
+ John Carpenter
+
+ // Incomplete code sample
+ wxDbTable users;
+ .....
+ users.SetWhereClause("");
+
+ // This Count() will return 4, as there are four users listed above
+ // that match the query parameters
+ totalNumberOfUsers = users.Count();
+
+ // This Count() will return 3, as there are only 3 unique first names
+ // in the table above - John, Richard, Michael.
+ totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
+\end{verbatim}
+
+\membersection{wxDbTable::CreateIndex}\label{wxdbtablecreateindex}
+
+\func{bool}{CreateIndex}{\param{const wxString \&}{IndexName}, \param{bool }{unique},
+\param{UWORD }{numIndexColumns}, \param{wxDbIdxDef *}{pIndexDefs},
+\param{bool }{attemptDrop=true}}
+
+This member function allows you to create secondary (non-primary) indexes on
+your tables. You first create your table, normally specifying a primary
+index, and then create any secondary indexes on the table. Indexes in
+relational model are not required. You do not need indexes to look up records
+in a table or to join two tables together. In the relational model, indexes,
+if available, provide a quicker means to look up data in a table. To enjoy
+the performance benefits of indexes, the indexes must be defined on the
+appropriate columns and your SQL code must be written in such a way as to
+take advantage of those indexes.
+
+\wxheading{Parameters}
+
+\docparam{IndexName}{Name of the Index. Name must be unique within the table
+space of the datasource.}
+\docparam{unique}{Indicates if this index is unique.}
+\docparam{numIndexColumns}{Number of columns in the index.}
+\docparam{pIndexDefs}{A pointer to an array \helpref{wxDbIdxDef}{wxdbidxdef} structures. }
+\docparam{attemptDrop}{{\it OPTIONAL}. Indicates if the function should try
+to execute a \helpref{wxDbTable::DropIndex}{wxdbtabledropindex} on the index
+name provided before trying to create the index name. Default is true.}
+
+\wxheading{Remarks}
+
+The first parameter, index name, must be unique and should be given a
+meaningful name. Common practice is to include the table name as a prefix
+in the index name (e.g. For table PARTS, you might want to call your index
+PARTS\_Index1). This will allow you to easily view all
+of the indexes defined for a given table grouped together alphabetically.
+
+The second parameter indicates if the index is unique or not. Uniqueness
+is enforced at the RDBMS level preventing rows which would have duplicate
+indexes from being inserted into the table when violating a unique index's
+uniqueness.
+
+In the third parameter, specify how many columns are in your index. This
+number must match the number of columns defined in the 'pIndexDefs' parameter.
+
+The fourth parameter specifies which columns make up the index using the
+\helpref{wxDbIdxDef}{wxdbidxdef} structure. For each column in the index, you must specify two
+things, the column name and the sort order (ascending / descending). See
+the example below to see how to build and pass in the \helpref{wxDbIdxDef}{wxdbidxdef} structure.
+
+The fifth parameter is provided to handle the differences in datasources as
+to whether they will automatically overwrite existing indexes with the same
+name or not. Some datasources require that the existing index must be dropped
+first, so this is the default behavior.
+
+Some datasources (MySQL, and possibly others) require columns which are to be
+part of an index to be defined as NOT NULL. When this function is called, if
+a column is not defined to be NOT NULL, a call to this function will modify
+the column definition to change any columns included in the index to be
+NOT NULL. In this situation, if a NULL value already exists in one of the
+columns that is being modified, creation of the index will fail.
+
+PostGres is unable to handle index definitions which specify whether the index
+is ascending or descending, and defaults to the system default when the index
+is created.
+
+It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
+after executing this function.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Create a secondary index on the PARTS table
+ wxDbIdxDef IndexDef[2]; // 2 columns make up the index
+
+ wxStrcpy(IndexDef[0].ColName, "PART_DESC"); // Column 1
+ IndexDef[0].Ascending = true;
+
+ wxStrcpy(IndexDef[1].ColName, "SERIAL_NO"); // Column 2
+ IndexDef[1].Ascending = false;
+
+ // Create a name for the index based on the table's name
+ wxString indexName;
+ indexName.Printf("%s_Index1",parts->GetTableName());
+ parts->CreateIndex(indexName, true, 2, IndexDef);
+\end{verbatim}
+
+\membersection{wxDbTable::CreateTable}\label{wxdbtablecreatetable}
+
+\func{bool}{CreateTable}{\param{bool }{attemptDrop=true}}
+
+Creates a table based on the definitions previously defined for this
+wxDbTable instance.
+
+\wxheading{Parameters}
+
+\docparam{attemptDrop}{{\it OPTIONAL}. Indicates whether the driver should
+attempt to drop the table before trying to create it. Some datasources will
+not allow creation of a table if the table already exists in the table space
+being used. Default is true.}
+
+\wxheading{Remarks}
+
+This function creates the table and primary index (if any) in the table space
+associated with the connected datasource. The owner of these objects will
+be the user id that was given when \helpref{wxDb::Open}{wxdbopen} was called.
+The objects will be created in the default schema/table space for that user.
+
+In your derived wxDbTable object constructor, the columns and primary index
+of the table are described through the \helpref{wxDbColDef}{wxdbcoldef} structure.
+\helpref{wxDbTable::CreateTable}{wxdbtablecreatetable} uses this information
+to create the table and to add the primary index. See
+\helpref{wxDbTable}{wxdbtable} ctor and wxDbColDef description for additional
+information on describing the columns of the table.
+
+It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
+after executing this function.
+
+\membersection{wxDbTable::DB\_STATUS}\label{wxdbtabledbstatus}
+
+\func{bool}{DB\_STATUS}{\void}
+
+Accessor function that returns the wxDb private member variable DB\_STATUS for
+the database connection used by this instance of wxDbTable.
+
+\membersection{wxDbTable::Delete}\label{wxdbtabledelete}
+
+\func{bool}{Delete}{\void}
+
+Deletes the row from the table indicated by the current cursor.
+
+\wxheading{Remarks}
+
+Use \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst},
+\helpref{wxDbTable::GetLast}{wxdbtablegetlast},
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext} or
+\helpref{wxDbTable::GetPrev}{wxdbtablegetprev} to position the cursor to
+a valid record. Once positioned on a record, call this function to delete
+the row from the table.
+
+A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
+this function to commit or rollback the deletion.
+
+NOTE: Most datasources have a limited size "rollback" segment. This means
+that it is only possible to insert/update/delete a finite number of rows
+without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}. Size of the rollback
+segment varies from database to database, and is user configurable in
+most databases. Therefore it is usually best to try to perform a commit
+or rollback at relatively small intervals when processing a larger number
+of actions that insert/update/delete rows in a table.
+
+\membersection{wxDbTable::DeleteCursor}\label{wxdbtabledeletecursor}
+
+\func{bool}{DeleteCursor}{\param{HSTMT *}{hstmtDel}}
+
+Allows a program to delete a cursor.
+
+\wxheading{Parameters}
+
+\docparam{hstmtDel}{Handle of the cursor to delete.}
+
+\wxheading{Remarks}
+
+For default cursors associated with the instance of wxDbTable, it is not
+necessary to specifically delete the cursors. This is automatically done
+in the wxDbTable destructor.
+
+NOTE: If the cursor could not be deleted for some reason, an error is logged
+indicating the reason. Even if the cursor could not be deleted, the HSTMT
+that is passed in is deleted, and the pointer is set to NULL.
+
+\normalbox{DO NOT DELETE THE wxDB\_DEFAULT\_CURSOR!}
+
+\membersection{wxDbTable::DeleteMatching}\label{wxdbtabledeletematching}
+
+\func{bool}{DeleteMatching}{\void}
+
+This member function allows you to delete records from your wxDbTable object
+by specifying the data in the columns to match on.
+
+\wxheading{Remarks}
+
+To delete all users with a first name of "JOHN", do the following:
+
+\begin{enumerate}\itemsep=0pt
+\item Clear all "columns" using wxDbTable::ClearMemberVars().
+\item Set the FIRST\_NAME column equal to "JOHN".
+\item Call wxDbTable::DeleteMatching().
+\end{enumerate}
+
+The WHERE clause is built by the ODBC class library based on all non-NULL
+columns. This allows deletion of records by matching on any column(s) in
+your wxDbTable instance, without having to write the SQL WHERE clause.
+
+A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
+this function to commit or rollback the deletion.
+
+NOTE: Row(s) should be locked before deleting them to make sure they are
+not already in use. This can be achieved by calling
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching},
+and then retrieving the records, locking each as you go (assuming FOR UPDATE
+is allowed on the datasource). After the row(s) have been successfully locked,
+call this function.
+
+NOTE: Most datasources have a limited "rollback" segment. This means
+that it is only possible to insert/update/delete a finite number of rows
+without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}. Size of the rollback
+segment varies from database to database, and is user configurable in
+most databases. Therefore it is usually best to try to perform a commit
+or rollback at relatively small intervals when processing a larger number
+of actions that insert/update/delete rows in a table.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample to delete all users with a first name
+ // of "JOHN"
+ users.ClearMemberVars();
+ wxStrcpy(users.FirstName,"JOHN");
+ users.DeleteMatching();
+\end{verbatim}
+
+
+\membersection{wxDbTable::DeleteWhere}\label{wxdbtabledeletewhere}
+
+\func{bool}{DeleteWhere}{\param{const wxString \&}{pWhereClause}}
+
+Deletes all rows from the table which match the criteria specified in the
+WHERE clause that is passed in.
+
+\wxheading{Parameters}
+
+\docparam{pWhereClause}{SQL WHERE clause. This WHERE clause determines which
+records will be deleted from the table interfaced through the wxDbTable
+instance. The WHERE clause passed in must be compliant with the SQL 92
+grammar. Do not include the keyword 'WHERE'
+}
+
+\wxheading{Remarks}
+
+This is the most powerful form of the wxDbTable delete functions. This
+function gives access to the full power of SQL. This function can be used
+to delete records by passing a valid SQL WHERE clause. Sophisticated
+deletions can be performed based on multiple criteria using the full
+functionality of the SQL language.
+
+A \helpref{wxDb::CommitTrans}{wxdbcommittrans} must be called after use of
+this function to commit the deletions.
+
+Note: This function is limited to deleting records from the table associated
+with this wxDbTable object only. Deletions on joined tables is not possible.
+
+NOTE: Most datasources have a limited size "rollback" segment. This means
+that it is only possible to insert/update/delete a finite number of rows
+without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}. Size of the rollback
+segment varies from database to database, and is user configurable in
+most databases. Therefore it is usually best to try to perform a commit
+or rollback at relatively small intervals when processing a larger number
+of actions that insert/update/delete rows in a table.
+
+WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Delete parts 1 thru 10 from containers 'X', 'Y' and 'Z' that
+ // are magenta in color
+ parts.DeleteWhere("(PART_NUMBER BETWEEN 1 AND 10) AND \
+ CONTAINER IN ('X', 'Y', 'Z') AND \
+ UPPER(COLOR) = 'MAGENTA'");
+\end{verbatim}
+
+
+\membersection{wxDbTable::DropIndex}\label{wxdbtabledropindex}
+
+\func{bool}{DropIndex}{\param{const wxString \&}{IndexName}}
+
+Allows an index on the associated table to be dropped (deleted) if the user
+login has sufficient privileges to do so.
+
+\wxheading{Parameters}
+
+\docparam{IndexName}{Name of the index to be dropped.}
+
+\wxheading{Remarks}
+
+If the index specified in the 'IndexName' parameter does not exist, an error
+will be logged, and the function will return a result of false.
+
+It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
+after executing this function.
+
+\membersection{wxDbTable::DropTable}\label{wxdbtabledroptable}
+
+\func{bool}{DropTable}{\void}
+
+Deletes the associated table if the user has sufficient privileges to do so.
+
+\wxheading{Remarks}
+
+This function returns true if the table does not exist, but only for
+supported databases (see \helpref{wxDb::Dbms}{wxdbdbms}). If a datasource
+is not specifically supported, and this function is called, the function
+will return false.
+
+Most datasources/ODBC drivers will delete any indexes associated with the
+table automatically, and others may not. Check the documentation for your
+database to determine the behavior.
+
+It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
+after executing this function.
+
+\membersection{wxDbTable::From}\label{wxdbtablefrom}
+
+\func{const wxString \&}{From}{}
+
+\func{void}{From}{\param{const wxString \&}{From}}
+
+Accessor function for the private class member wxDbTable::from. Can be used
+as a synonym for \helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
+(the first form of this function) or
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} (the second form
+of this function).
+
+\wxheading{Parameters}
+
+\docparam{From}{A comma separated list of table names that are to be inner
+joined with the base table's columns so that the joined table's columns
+may be returned in the result set or used as a portion of a comparison with
+the base table's columns. NOTE that the base tables name must NOT be included
+in the FROM clause, as it is automatically included by the wxDbTable class
+in constructing query statements.}
+
+\wxheading{Return value}
+
+The first form of this function returns the current value of the wxDbTable
+member variable ::from.
+
+The second form of the function has no return value, as it will always set
+the from clause successfully.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause},
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
+
+
+\membersection{wxDbTable::GetColDefs}\label{wxdbtablegetcoldefs}
+
+\func{wxDbColDef *}{GetColDefs}{}
+
+Accessor function that returns a pointer to the array of column definitions
+that are bound to the columns that this wxDbTable instance is associated
+with.
+
+To determine the number of elements pointed to by the returned
+\helpref{wxDbColDef}{wxdbcoldef} pointer, use the
+\helpref{wxDbTable::GetNumberOfColumns}{wxdbtablegetnumberofcolumns} function.
+
+\wxheading{Remarks}
+
+These column definitions must not be manually redefined after they have been
+set.
+
+\membersection{wxDbTable::GetCursor}\label{wxdbtablegetcursor}
+
+\func{HSTMT}{GetCursor}{\void}
+
+Returns the HSTMT value of the current cursor for this wxDbTable object.
+
+\wxheading{Remarks}
+
+This function is typically used just before changing to use a different cursor
+so that after the program is finished using the other cursor, the current
+cursor can be set back to being the cursor in use.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}, \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor}
+
+\membersection{wxDbTable::GetDb}\label{wxdbtablegetdb}
+
+\func{wxDb *}{GetDb}{}
+
+Accessor function for the private member variable pDb which is a pointer to
+the datasource connection that this wxDbTable instance uses.
+
+\membersection{wxDbTable::GetFirst}\label{wxdbtablegetfirst}
+
+\func{bool}{GetFirst}{\void}
+
+Retrieves the FIRST row in the record set as defined by the current query.
+Before retrieving records, a query must be performed using
+\helpref{wxDbTable::Query}{wxdbtablequery},
+\helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
+\helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
+
+\wxheading{Remarks}
+
+This function can only be used if the datasource connection used by the
+wxDbTable instance was created with FwdOnlyCursors set to false. If the
+connection does not allow backward scrolling cursors, this function will
+return false, and the data contained in the bound columns will be undefined.
+
+\wxheading{See also}
+
+\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
+
+\membersection{wxDbTable::GetFromClause}\label{wxdbtablegetfromclause}
+
+\func{const wxString \&}{GetFromClause}{}
+
+Accessor function that returns the current FROM setting assigned with the
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::From}{wxdbtablefrom}
+
+\membersection{wxDbTable::GetLast}\label{wxdbtablegetlast}
+
+\func{bool}{GetLast}{\void}
+
+Retrieves the LAST row in the record set as defined by the current query.
+Before retrieving records, a query must be performed using
+\helpref{wxDbTable::Query}{wxdbtablequery},
+\helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
+\helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
+
+\wxheading{Remarks}
+
+This function can only be used if the datasource connection used by the
+wxDbTable instance was created with FwdOnlyCursors set to false. If the
+connection does not allow backward scrolling cursors, this function will
+return false, and the data contained in the bound columns will be undefined.
+
+\wxheading{See also}
+
+\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
+
+\membersection{wxDbTable::GetNewCursor}\label{wxdbtablegetnewcursor}
+
+\func{HSTMT *}{GetNewCursor}{\param{bool }{setCursor=false},
+\param{bool }{bindColumns=true}}
+
+This function will create a new cursor that can be used to access the table
+being referenced by this wxDbTable instance, or to execute direct SQL commands
+on without affecting the cursors that are already defined and possibly
+positioned.
+
+\wxheading{Parameters}
+
+\docparam{setCursor}{{\it OPTIONAL}. Should this new cursor be set to be the
+current cursor after successfully creating the new cursor. Default is false.}
+\docparam{bindColumns}{{\it OPTIONAL}. Should this new cursor be bound to all
+the memory variables that the default cursor is bound to. Default is true.}
+
+\wxheading{Remarks}
+
+This new cursor must be closed using
+\helpref{wxDbTable::DeleteCursor}{wxdbtabledeletecursor}
+by the calling program before the wxDbTable instance is deleted, or both
+memory and resource leaks will occur.
+
+\membersection{wxDbTable::GetNext}\label{wxdbtablegetnext}
+
+\func{bool}{GetNext}{\void}
+
+Retrieves the NEXT row in the record set after the current cursor position
+as defined by the current query. Before retrieving records, a query must be
+performed using \helpref{wxDbTable::Query}{wxdbtablequery},
+\helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
+\helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
+
+\wxheading{Return value}
+
+This function returns false when the current cursor has reached the end of
+the result set. When false is returned, data in the bound columns is
+undefined.
+
+\wxheading{Remarks}
+
+This function works with both forward and backward scrolling cursors.
+
+\wxheading{See also}
+\helpref{wxDbTable::++}{wxdbtableplusplus}
+
+\membersection{wxDbTable::GetNumberOfColumns}\label{wxdbtablegetnumberofcolumns}
+
+\func{UWORD }{GetNumberOfColumns}{}
+
+Accessor function that returns the number of columns that are statically
+bound for access by the wxDbTable instance.
+
+\membersection{wxDbTable::GetOrderByClause}\label{wxdbtablegetorderbyclause}
+
+\func{const wxString \&}{GetOrderByClause}{}
+
+Accessor function that returns the current ORDER BY setting assigned with
+the \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::OrderBy}{wxdbtableorderby}
+
+\membersection{wxDbTable::GetPrev}\label{wxdbtablegetprev}
+
+\func{bool}{GetPrev}{\void}
+
+Retrieves the PREVIOUS row in the record set before the current cursor
+position as defined by the current query. Before retrieving records, a
+query must be performed using \helpref{wxDbTable::Query}{wxdbtablequery},
+\helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields},
+\helpref{wxDbTable::QueryMatching}{wxdbtablequerymatching} or
+\helpref{wxDbTable::QueryBySqlStmt}{wxdbtablequerybysqlstmt}.
+
+\wxheading{Return value}
+
+This function returns false when the current cursor has reached the beginning
+of the result set and there are now other rows prior to the cursors current
+position. When false is returned, data in the bound columns is undefined.
+
+\wxheading{Remarks}
+
+This function can only be used if the datasource connection used by the
+wxDbTable instance was created with FwdOnlyCursors set to false. If the
+connection does not allow backward scrolling cursors, this function will
+return false, and the data contained in the bound columns will be undefined.
+
+\wxheading{See also}
+
+\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors},
+\helpref{wxDbTable::--}{wxdbtableminusminus}
+
+\membersection{wxDbTable::GetQueryTableName}\label{wxdbtablegetquerytablename}
+
+\func{const wxString \&}{GetQueryTableName}{}
+
+Accessor function that returns the name of the table/view that was indicated
+as being the table/view to query against when this wxDbTable instance was
+created.
+
+\wxheading{See also}
+
+\helpref{wxDbTable constructor}{wxdbtableconstr}
+
+\membersection{wxDbTable::GetRowNum}\label{wxdbtablegetrownum}
+
+\func{UWORD}{GetRowNum}{\void}
+
+Returns the ODBC row number for performing positioned updates and deletes.
+
+\wxheading{Remarks}
+
+This function is not being used within the ODBC class library and may be a
+candidate for removal if no use is found for it.
+
+Row number with some datasources/ODBC drivers is the position in the result set,
+while in others it may be a physical position in the database. Check your
+database documentation to find out which behavior is supported.
+
+\membersection{wxDbTable::GetTableName}\label{wxdbtablegettablename}
+
+\func{const wxString \&}{GetTableName}{}
+
+Accessor function that returns the name of the table that was indicated
+as being the table that this wxDbTable instance was associated with.
+
+\membersection{wxDbTable::GetTablePath}\label{wxdbtablegettablepath}
+
+\func{const wxString \&}{GetTablePath}{}
+
+Accessor function that returns the path to the data table that was indicated
+during creation of this wxDbTable instance.
+
+\wxheading{Remarks}
+
+Currently only applicable to dBase and MS-Access datasources.
+
+\membersection{wxDbTable::GetWhereClause}\label{wxdbtablegetwhereclause}
+
+\func{const wxString \&}{GetWhereClause}{}
+
+Accessor function that returns the current WHERE setting assigned with the
+\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+
+\wxheading{See also}
+
+\helpref{wxDbTable::Where}{wxdbtablewhere}
+
+\membersection{wxDbTable::Insert}\label{wxdbtableinsert}
+
+\func{int }{Insert}{\void}
+
+Inserts a new record into the table being referenced by this wxDbTable
+instance. The values in the member variables of the wxDbTable instance are
+inserted into the columns of the new row in the database.
+
+\wxheading{Return value}
+
+\begin{verbatim}
+ DB_SUCCESS Record inserted successfully (value = 1)
+
+ DB_FAILURE Insert failed (value = 0)
+
+ DB_ERR_INTEGRITY_CONSTRAINT_VIOL
+ The insert failed due to an integrity
+ constraint violation (duplicate non-unique
+ index entry) is attempted.
+\end{verbatim}
+
+\wxheading{Remarks}
+
+A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
+this function to commit or rollback the insertion.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code snippet
+ wxStrcpy(parts->PartName, "10");
+ wxStrcpy(parts->PartDesc, "Part #10");
+ parts->Qty = 1000;
+ RETCODE retcode = parts->Insert();
+ switch(retcode)
+ {
+ case DB_SUCCESS:
+ parts->GetDb()->CommitTrans();
+ return(true);
+ case DB_ERR_INTEGRITY_CONSTRAINT_VIOL:
+ // Current data would result in a duplicate key
+ // on one or more indexes that do not allow duplicates
+ parts->GetDb()->RollbackTrans();
+ return(false);
+ default:
+ // Insert failed for some unexpected reason
+ parts->GetDb()->RollbackTrans();
+ return(false);
+ }
+\end{verbatim}
+
+\membersection{wxDbTable::IsColNull}\label{wxdbtableiscolnull}
+
+\func{bool }{IsColNull}{\param{UWORD }{colNumber}} const
+
+Used primarily in the ODBC class library to determine if a column value is
+set to "NULL". Works for all data types supported by the ODBC class library.
+
+\wxheading{Parameters}
+
+\docparam{colNumber}{The column number of the bound column as defined by the
+\helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
+calls which defined the columns accessible to this wxDbTable instance.}
+
+\wxheading{Remarks}
+
+NULL column support is currently not fully implemented as of wxWidgets 2.4.
+
+\membersection{wxDbTable::IsCursorClosedOnCommit}\label{wxdbtableiscursorclosedoncommit}
+
+\func{bool }{IsCursorClosedOnCommit}{\void}
+
+Accessor function to return information collected during the opening of the
+datasource connection that is used by this wxDbTable instance. The result
+returned by this function indicates whether an implicit closing of the cursor is
+done after a commit on the database connection.
+
+\wxheading{Return value}
+
+Returns true if the cursor associated with this wxDbTable object is closed
+after a commit or rollback operation. Returns false otherwise.
+
+\wxheading{Remarks}
+
+If more than one wxDbTable instance used the same database connection, all cursors
+which use the database connection are closed on the commit if this function
+indicates true.
+
+\membersection{wxDbTable::IsQueryOnly}\label{wxdbtableisqueryonly}
+
+\func{bool }{IsQueryOnly}{}
+
+Accessor function that returns a value indicating if this wxDbTable instance
+was created to allow only queries to be performed on the bound columns. If
+this function returns true, then no actions may be performed using this
+wxDbTable instance that would modify (insert/delete/update) the table's data.
+
+\membersection{wxDbTable::Open}\label{wxdbtableopen}
+
+\func{bool }{Open}{\param{bool }{checkPrivileges=false}, \param{bool }{checkTableExists=true}}
+
+Every wxDbTable instance must be opened before it can be used. This function
+checks for the existence of the requested table, binds columns, creates required
+cursors, (insert/select and update if connection is not wxDB\_QUERY\_ONLY) and
+constructs the insert statement that is to be used for inserting data as a new
+row in the datasource.
+
+NOTE: To retrieve data into an opened table, the of the table must be bound
+to the variables in the program via call(s) to
+\helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} before calling Open().
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\wxheading{Parameters}
+
+\docparam{checkPrivileges}{Indicates whether the Open() function should check
+whether the current connected user has at least SELECT privileges to access the
+table to which they are trying to open. Default is false.}
+
+\docparam{checkTableExists}{Indicates whether the Open() function should check
+whether the table exists in the database or not before opening it. Default is true.}
+
+\wxheading{Remarks}
+
+If the function returns a false value due to the table not existing, a log
+entry is recorded for the datasource connection indicating the problem
+that was detected when checking for table existence. Note that it is usually
+best for the calling routine to check for the existence of the table and for
+sufficient user privileges to access the table in the mode (wxDB\_QUERY\_ONLY or
+!wxDB\_QUERY\_ONLY) before trying to open the table for the best possible
+explanation as to why a table cannot be opened.
+
+Checking the user's privileges on a table can be quite time consuming during
+the open phase. With most applications, the programmer already knows that the
+user has sufficient privileges to access the table, so this check is normally
+not required.
+
+For best performance, open the table, and then use the
+\helpref{wxDb::TablePrivileges}{wxdbtableprivileges} function
+to check the users privileges. Passing a schema to the TablePrivileges()
+function can significantly speed up the privileges checks.
+
+\wxheading{See also}
+
+\helpref{wxDb::TableExists}{wxdbtableexists},
+\helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
+\helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
+
+\membersection{wxDbTable::OrderBy}\label{wxdbtableorderby}
+
+\func{const wxString \&}{OrderBy}{}
+
+\func{void}{OrderBy}{\param{const wxString \&}{OrderBy}}
+
+Accessor function for the private class member wxDbTable::orderBy. Can be
+used as a synonym for
+\helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
+(the first form of this function) or
+\helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}
+(the second form of this function).
+
+\wxheading{Parameters}
+
+\docparam{OrderBy}{A comma separated list of column names that indicate the
+alphabetized/numeric sorting sequence that the result set is to be returned
+in. If a FROM clause has also been specified, each column name specified in
+the ORDER BY clause should be prefaced with the table name to which the column
+belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
+
+\wxheading{Return value}
+
+The first form of this function returns the current value of the wxDbTable
+member variable ::orderBy.
+
+The second form of the function has no return value.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause},
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}
+
+\membersection{wxDbTable::Query}\label{wxdbtablequery}
+
+\func{virtual bool }{Query}{\param{bool }{forUpdate=false}, \param{bool }{distinct=false}}
+
+\wxheading{Parameters}
+
+\docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
+as they are retrieved. If the RDBMS is not capable of the FOR UPDATE clause,
+this argument is ignored. See
+\helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
+additional information regarding this argument. Default is false.}
+\docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
+from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
+applies to all columns returned in the result set, not individual columns.
+Default is false.}
+
+\wxheading{Remarks}
+
+This function queries records from the datasource based on the three
+wxDbTable members: "where", "orderBy", and "from". Use
+\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} to filter on
+records to be retrieved (e.g. All users with a first name of "JOHN").
+Use \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause} to
+change the sequence in which records are returned in the result set from
+the datasource (e.g. Ordered by LAST\_NAME). Use
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} to allow inner
+joining of the base table (the one being associated with this instance of
+wxDbTable) with other tables which share a related field.
+
+After each of these clauses are set/cleared, call wxDbTable::Query() to
+fetch the result set from the datasource.
+
+This scheme has an advantage if you have to requery your record set
+frequently in that you only have to set your WHERE, ORDER BY, and FROM
+clauses once. Then to refresh the record set, simply call wxDbTable::Query()
+as frequently as needed.
+
+Note that repeated calls to wxDbTable::Query() may tax the database
+server and make your application sluggish if done too frequently or
+unnecessarily.
+
+The base table name is automatically prepended to the base column names in
+the event that the FROM clause has been set (is non-null) using
+\helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
+
+The cursor for the result set is positioned {\it before} the first record in
+the result set after the query. To retrieve the first record, call either
+\helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} (only if backward scrolling
+cursors are available) or
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}. Typically, no data from the
+result set is returned to the client driver until a request such as
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext} is performed, so network
+traffic and database load are not overwhelmed transmitting data until the
+data is actually requested by the client. This behavior is solely dependent
+on the ODBC driver though, so refer to the ODBC driver's reference material
+for information on its behaviors.
+
+Values in the bound columns' memory variables are undefined after executing a
+call to this function and remain that way until a row in the result set is
+requested to be returned.
+
+The wxDbTable::Query() function is defined as "virtual" so that it may be
+overridden for application specific purposes.
+
+\normalbox{Be sure to set the wxDbTable's "where", "orderBy", and "from"
+member variables to "" if they are not to be used in the query. Otherwise,
+the results returned may have unexpected results (or no results) due to
+improper or incorrect query parameters constructed from the uninitialized
+clauses.}
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ parts->SetWhereClause("DESCRIPTION = 'FOOD'");
+ parts->SetOrderByClause("EXPIRATION_DATE");
+ parts->SetFromClause("");
+ // Query the records based on the where, orderBy and from clauses
+ // specified above
+ parts->Query();
+ // Display all records queried
+ while(parts->GetNext())
+ dispPart(parts); // user defined function
+\end{verbatim}
+
+\membersection{wxDbTable::QueryBySqlStmt}\label{wxdbtablequerybysqlstmt}
+
+\func{bool}{QueryBySqlStmt}{\param{const wxString \&}{pSqlStmt}}
+
+Performs a query against the datasource by accepting and passing verbatim the
+SQL SELECT statement passed to the function.
+
+\wxheading{Parameters}
+
+\docparam{pSqlStmt}{Pointer to the SQL SELECT statement to be executed.}
+
+\wxheading{Remarks}
+
+This is the most powerful form of the query functions available. This member
+function allows a programmer to write their own custom SQL SELECT statement
+for requesting data from the datasource. This gives the programmer access
+to the full power of SQL for performing operations such as scalar functions,
+aggregate functions, table joins, and sub-queries, as well as datasource
+specific function calls.
+
+The requirements of the SELECT statement are the following:
+
+\begin{enumerate}
+\item Must return the correct number of columns. In the derived
+wxDbTable constructor, it is specified how many columns are in
+the wxDbTable object. The SELECT statement must return exactly
+that many columns.
+\item The columns must be returned in the same sequence as specified
+when defining the bounds columns \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs},
+and the columns returned must be of the proper data type. For
+example, if column 3 is defined in the wxDbTable bound column
+definitions to be a float, the SELECT statement must return a
+float for column 3 (e.g. PRICE * 1.10 to increase the price by
+10%).
+\item The ROWID can be included in your SELECT statement as the {\bf last}
+column selected, if the datasource supports it. Use
+wxDbTable::CanUpdateByROWID() to determine if the ROWID can be
+selected from the datasource. If it can, much better
+performance can be achieved on updates and deletes by including
+the ROWID in the SELECT statement.
+\end{enumerate}
+
+Even though data can be selected from multiple tables (joins) in your select
+statement, only the base table associated with this wxDbTable object
+is automatically updated through the ODBC class library. Data from multiple
+tables can be selected for display purposes however. Include columns in
+the wxDbTable object and mark them as non-updateable (See
+\helpref{wxDbColDef}{wxdbcoldef} for details). This way columns can be
+selected and displayed from other tables, but only the base table will be
+updated automatically when performed through the
+\helpref{wxDbTable::Update}{wxdbtableupdate} function after using this type of
+query. To update tables other than the base table, use the
+\helpref{wxDbTable::Update}{wxdbtableupdate} function passing a SQL statement.
+
+After this function has been called, the cursor is positioned before the
+first record in the record set. To retrieve the first record, call
+either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code samples
+ wxString sqlStmt;
+ sqlStmt = "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
+ AND CONTAINER = 12";
+ // Query the records using the SQL SELECT statement above
+ parts->QueryBySqlStmt(sqlStmt);
+ // Display all records queried
+ while(parts->GetNext())
+ dispPart(&parts);
+
+ Example SQL statements
+ ----------------------
+
+ // Table Join returning 3 columns
+ SELECT PART_NUM, part_desc, sd_name
+ from parts, storage_devices
+ where parts.storage_device_id =
+ storage_devices.storage_device_id
+
+ // Aggregate function returning total number of
+ // parts in container 99
+ SELECT count(*) from PARTS where container = 99
+
+ // Order by clause; ROWID, scalar function
+ SELECT PART_NUM, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
+ from parts
+ where warehouse = 10
+ order by PART_NUM desc // descending order
+
+ // Subquery
+ SELECT * from parts
+ where container in (select container
+ from storage_devices
+ where device_id = 12)
+\end{verbatim}
+
+\membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
+
+\func{virtual bool }{QueryMatching}{\param{bool }{forUpdate=false},
+\param{bool }{distinct=false}}
+
+QueryMatching allows querying of records from the table associated with
+the wxDbTable object by matching "columns" to values.
+
+For example: To query the datasource for the row with a PART\_NUMBER column
+value of "32", clear all column variables of the wxDbTable object, set the
+PartNumber variable that is bound to the PART\_NUMBER column in the wxDbTable
+object to "32", and then call wxDbTable::QueryMatching().
+
+\wxheading{Parameters}
+
+\docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
+as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
+the FOR UPDATE clause, this argument is ignored. See
+\helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
+additional information regarding this argument. Default is false.}
+\docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
+from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
+applies to all columns returned in the result set, not individual columns.
+Default is false.}
+
+\wxheading{Remarks}
+
+The SQL WHERE clause is built by the ODBC class library based on all
+non-zero/non-NULL columns in your wxDbTable object. Matches can be on one,
+many or all of the wxDbTable's columns. The base table name is prepended
+to the column names in the event that the wxDbTable's FROM clause is non-null.
+
+This function cannot be used to perform queries which will check for
+columns that are 0 or NULL, as the automatically constructed WHERE clause
+only will contain comparisons on column member variables that are
+non-zero/non-NULL.
+
+The primary difference between this function and \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields}
+is that this function can query on any column(s) in the wxDbTable object.
+Note however that this may not always be very efficient. Searching on
+non-indexed columns will always require a full table scan.
+
+The cursor is positioned before the first record in the record set after
+the query is performed. To retrieve the first record, the program must call
+either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
+
+WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ parts->ClearMemberVars(); // Set all columns to zero
+ wxStrcpy(parts->PartNumber,"32"); // Set columns to query on
+ parts->OnHold = true;
+ parts->QueryMatching(); // Query
+ // Display all records queried
+ while(parts->GetNext())
+ dispPart(parts); // Some application defined function
+\end{verbatim}
+
+\membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
+
+\func{bool }{QueryOnKeyFields}{\param{bool }{forUpdate=false},
+\param{bool }{distinct=false}}
+
+QueryOnKeyFields provides an easy mechanism to query records in the table
+associated with the wxDbTable object by the primary index column(s). Simply
+assign the primary index column(s) values and then call this member function
+to retrieve the record.
+
+Note that since primary indexes are always unique, this function implicitly
+always returns a single record from the database. The base table name is
+prepended to the column names in the event that the wxDbTable's FROM clause
+is non-null.
+
+\wxheading{Parameters}
+
+\docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
+as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
+the FOR UPDATE clause, this argument is ignored. See
+\helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
+additional information regarding this argument. Default is false.}
+\docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
+from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
+applies to all columns returned in the result set, not individual columns.
+Default is false.}
+
+\wxheading{Remarks}
+
+The cursor is positioned before the first record in the record set after
+the query is performed. To retrieve the first record, the program must call
+either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
+
+WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ wxStrcpy(parts->PartNumber, "32");
+ parts->QueryOnKeyFields();
+ // Display all records queried
+ while(parts->GetNext())
+ dispPart(parts); // Some application defined function
+\end{verbatim}
+
+\membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
+
+\func{bool}{Refresh}{\void}
+
+This function re-reads the bound columns into the memory variables, setting
+them to the current values stored on the disk.
+
+The cursor position and result set are unaffected by calls to this function.
+(The one exception is in the case where the record to be refreshed has been
+deleted by some other user or transaction since it was originally retrieved
+as part of the result set. For most datasources, the default behavior in
+this situation is to return the value that was originally queried for the
+result set, even though it has been deleted from the database. But this is
+datasource dependent, and should be tested before relying on this behavior.)
+
+\wxheading{Remarks}
+
+This routine is only guaranteed to work if the table has a unique primary
+index defined for it. Otherwise, more than one record may be fetched and
+there is no guarantee that the correct record will be refreshed. The
+table's columns are refreshed to reflect the current data in the database.
+
+\membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
+
+\func{bool}{SetColDefs}{\param{UWORD }{index}, \param{const wxString \&}{fieldName},
+\param{int }{dataType}, \param{void *}{pData}, \param{SWORD }{cType},
+\param{int }{size}, \param{bool }{keyField = false}, \param{bool }{updateable = true},
+\param{bool }{insertAllowed = true}, \param{bool }{derivedColumn = false}}
+
+\func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{UWORD }{numCols}}
+
+\wxheading{Parameters}
+
+\docparam{index}{Column number (0 to n-1, where n is the number of columns
+specified as being defined for this wxDbTable instance when the
+wxDbTable constructor was called.}
+\docparam{fieldName}{Column name from the associated data table.}
+\docparam{dataType}{Logical data type. Valid logical types include:}
+
+\begin{verbatim}
+ DB_DATA_TYPE_VARCHAR : strings
+ DB_DATA_TYPE_INTEGER : non-floating point numbers
+ DB_DATA_TYPE_FLOAT : floating point numbers
+ DB_DATA_TYPE_DATE : dates
+ DB_DATA_TYPE_BLOB : binary large objects
+ DB_DATA_TYPE_MEMO : large strings
+\end{verbatim}
+
+\docparam{pData}{Pointer to the data object that will hold the column's
+value when a row of data is returned from the datasource.}
+\docparam{cType}{SQL C Type. This defines the data type that the SQL
+representation of the data is converted to to be stored in {\it pData}.
+Other valid types are available also, but these are the most common ones:}
+
+\begin{verbatim}
+ SQL_C_CHAR // string - deprecated: use SQL_C_WXCHAR
+ SQL_C_WXCHAR // string - Used transparently in unicode or non-unicode builds
+ SQL_C_LONG
+ SQL_C_ULONG
+ SQL_C_SHORT
+ SQL_C_USHORT
+ SQL_C_FLOAT
+ SQL_C_DOUBLE
+ SQL_C_NUMERIC
+ SQL_C_TIMESTAMP
+
+ SQL_C_BOOLEAN // defined in db.h
+ SQL_C_ENUM // defined in db.h
+\end{verbatim}
+
+\docparam{size}{Maximum size in bytes of the {\it pData} object.}
+\docparam{keyField}{{\it OPTIONAL}. Indicates if this column is part of the
+primary index. Default is false.}
+\docparam{updateable}{{\it OPTIONAL}. Are updates allowed on this column?
+Default is true.}
+\docparam{insertAllowed}{{\it OPTIONAL}. Inserts allowed on this column?
+Default is true.}
+\docparam{derivedColumn}{{\it OPTIONAL}. Is this a derived column (non-base
+table column for query only)? Default is false.}
+
+\docparam{colInfs}{Pointer to an array of wxDbColInf instances which contains
+all the information necessary to create {\it numCols} column definitions.}
+\docparam{numCols}{Number of elements of wxDbColInf type that are pointed
+to by {\it colInfs}, which are to have column definitions created from them.}
+
+\wxheading{Remarks}
+
+If {\it pData} is to hold a string of characters, be sure to include enough
+space for the NULL terminator in pData and in the byte count of {\it size}.
+
+Using the first form of this function, if the column definition is not able
+to be created, a value of false is returned. If the specified index of the
+column exceeds the number of columns defined in the wxDbTable instance, an
+assert is thrown and logged (in debug builds) and a false is returned.
+
+A failure to create the column definition in the second form results in a
+value of NULL being returned.
+
+Both forms of this function provide a shortcut for defining the columns in
+your wxDbTable object. Use this function in any derived wxDbTable
+constructor when describing the column/columns in the wxDbTable object.
+
+The second form of this function is primarily used when the
+\helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
+datasource for the column definitions, so that the column definitions are
+already stored in wxDbColInf form. One example use of using
+\helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
+a data table existed in one datasource, and the table's column definitions
+were to be copied over to another datasource or table.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Long way not using this function
+ wxStrcpy(colDefs[0].ColName, "PART_NUM");
+ colDefs[0].DbDataType = DB_DATA_TYPE_VARCHAR;
+ colDefs[0].PtrDataObj = PartNumber;
+ colDefs[0].SqlCtype = SQL_C_WXCHAR;
+ colDefs[0].SzDataObj = PART_NUMBER_LEN;
+ colDefs[0].KeyField = true;
+ colDefs[0].Updateable = false;
+ colDefs[0].InsertAllowed= true;
+ colDefs[0].DerivedCol = false;
+
+ // Shortcut using this function
+ SetColDefs(0, "PART_NUM", DB_DATA_TYPE_VARCHAR, PartNumber,
+ SQL_C_WXCHAR, PART_NUMBER_LEN, true, false, true, false);
+\end{verbatim}
+
+\membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
+
+\func{void}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB\_DEFAULT\_CURSOR}}
+
+\wxheading{Parameters}
+
+\docparam{hstmtActivate}{{\it OPTIONAL}. Pointer to the cursor that is to
+become the current cursor. Passing no cursor handle will reset the cursor
+back to the wxDbTable's default (original) cursor that was created when the
+wxDbTable instance was first created. Default is wxDB\_DEFAULT\_CURSOR.}
+
+\wxheading{Remarks}
+
+When swapping between cursors, the member variables of the wxDbTable object
+are automatically refreshed with the column values of the row that the
+current cursor is positioned at (if any). If the cursor is not positioned,
+then the data in member variables is undefined.
+
+The only way to return back to the cursor that was in use before this
+function was called is to programmatically determine the current cursor's HSTMT
+{\bf BEFORE} calling this function using \helpref{wxDbTable::GetCursor}{wxdbtablegetcursor}
+and saving a pointer to that cursor.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor},
+\helpref{wxDbTable::GetCursor}{wxdbtablegetcursor},
+\helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}
+
+\membersection{wxDbTable::SetFromClause}\label{wxdbtablesetfromclause}
+
+\func{void}{SetFromClause}{\param{const wxString \&}{From}}
+
+Accessor function for setting the private class member wxDbTable::from
+that indicates what other tables should be inner joined with the wxDbTable's
+base table for access to the columns in those other tables.
+
+Synonym to this function is one form of \helpref{wxDbTable::From}{wxdbtablefrom}
+
+\wxheading{Parameters}
+
+\docparam{From}{A comma separated list of table names that are to be inner
+joined with the base table's columns so that the joined table's columns
+may be returned in the result set or used as a portion of a comparison with
+the base table's columns. NOTE that the base tables name must NOT be included
+in the FROM clause, as it is automatically included by the wxDbTable class
+in constructing query statements.}
+
+\wxheading{Remarks}
+
+Used by the \helpref{wxDbTable::Query}{wxdbtablequery} and
+\helpref{wxDbTable::Count}{wxdbtablecount} member functions to allow inner
+joining of records from multiple tables.
+
+Do {\bf not} include the keyword "FROM" when setting the FROM clause.
+
+If using the FROM clause when performing a query, be certain to include in
+the corresponding WHERE clause a comparison of a column from either the base
+table or one of the other joined tables to each other joined table to ensure
+the datasource knows on which column values the tables should be joined on.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ ...
+ // Base table is the "LOCATION" table, and it is being
+ // inner joined to the "PART" table via the field "PART_NUMBER"
+ // that can be related between the two tables.
+ location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
+ location->SetFromClause("PART");
+ ...
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxDbTable::From}{wxdbtablefrom},
+\helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
+
+\membersection{wxDbTable::SetColNull}\label{wxdbtablesetcolnull}
+
+\func{bool}{SetColNull}{\param{UWORD }{colNumber}, \param{bool }{set=true}}
+
+\func{bool}{SetColNull}{\param{const wxString \&}{colName},
+\param{bool }{set=true}}
+
+Both forms of this function allow a member variable representing a column
+in the table associated with this wxDbTable object to be set to NULL.
+
+The first form allows the column to be set by the index into the column
+definitions used to create the wxDbTable instance, while the second allows
+the actual column name to be specified.
+
+\wxheading{Parameters}
+
+\docparam{colNumber}{Index into the column definitions used when first defining
+this wxDbTable object.}
+\docparam{colName}{Actual data table column name that is to be set to NULL.}
+\docparam{set}{Whether the column is set to NULL or not. Passing true sets
+the column to NULL, passing false sets the column to be non-NULL. Default is
+true.}
+
+\wxheading{Remarks}
+
+No database updates are done by this function. It only operates on the
+member variables in memory. Use and insert or update function to store this
+value to disk.
+
+\membersection{wxDbTable::SetOrderByClause}\label{wxdbtablesetorderbyclause}
+
+\func{void}{SetOrderByClause}{\param{const wxString \&}{OrderBy}}
+
+Accessor function for setting the private class member wxDbTable::orderBy
+which determines sequence/ordering of the rows returned in the result set
+of a query.
+
+A synonym to this function is one form of the function \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
+
+\wxheading{Parameters}
+
+\docparam{OrderBy}{A comma separated list of column names that indicate the
+alphabetized sorting sequence that the result set is to be returned in. If
+a FROM clause has also been specified, each column name specified in the
+ORDER BY clause should be prefaced with the table name to which the column
+belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
+
+\wxheading{Remarks}
+
+Do {\bf not} include the keywords "ORDER BY" when setting the ORDER BY clause.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ ...
+ parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
+ ...
+
+ ...
+ location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
+ ...
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxDbTable::OrderBy}{wxdbtableorderby},
+\helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
+
+\membersection{wxDbTable::SetQueryTimeout}\label{wxdbtablesetquerytimeout}
+
+\func{bool}{SetQueryTimeout}{\param{UDWORD }{nSeconds}}
+
+Allows a time period to be set as the timeout period for queries.
+
+\wxheading{Parameters}
+
+\docparam{nSeconds}{The number of seconds to wait for the query to complete
+before timing out.}
+
+\wxheading{Remarks}
+
+Neither Oracle or Access support this function as of yet. Other databases
+should be evaluated for support before depending on this function working
+correctly.
+
+\membersection{wxDbTable::SetWhereClause}\label{wxdbtablesetwhereclause}
+
+\func{void}{SetWhereClause}{\param{const wxString \&}{Where}}
+
+Accessor function for setting the private class member wxDbTable::where
+that determines which rows are returned in the result set by the datasource.
+
+A synonym to this function is one form of the function \helpref{wxDbTable::Where}{wxdbtablewhere}
+
+\wxheading{Parameters}
+
+\docparam{Where}{SQL "where" clause. This clause can contain any SQL language
+that is legal in standard where clauses. If a FROM clause has also been
+specified, each column name specified in the ORDER BY clause should be
+prefaced with the table name to which the column belongs using DOT notation
+(TABLE\_NAME.COLUMN\_NAME).}
+
+\wxheading{Remarks}
+
+Do {\bf not} include the keywords "WHERE" when setting the WHERE clause.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ ...
+ // Simple where clause
+ parts->SetWhereClause("PART_NUMBER = '32'");
+ ...
+ // Any comparison operators
+ parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER%'");
+ ...
+ // Multiple comparisons, including a function call
+ parts->Where("QTY > 0 AND {fn UCASE(PART_DESCRIP)} LIKE '%DRILL%'");
+ ...
+ // Using parameters and multiple logical combinations
+ parts->Where("((QTY > 10) OR (ON_ORDER > 0)) AND ON_HOLD = 0");
+ ...
+ // This query uses an inner join (requiring a FROM clause also)
+ // that joins the PART and LOCATION table on he common field
+ // PART_NUMBER.
+ parts->Where("PART.ON_HOLD = 0 AND \
+ PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
+ LOCATION.PART_NUMBER > 0");
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxDbTable::Where}{wxdbtablewhere},
+\helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
+
+\membersection{wxDbTable::Update}\label{wxdbtableupdate}
+
+\func{bool }{Update}{\void}
+
+\func{bool }{Update}{\param{const wxString \&}{pSqlStmt}}
+
+The first form of this function will update the row that the current cursor
+is currently positioned at with the values in the memory variables that
+are bound to the columns. The actual SQL statement to perform the update
+is automatically created by the ODBC class, and then executed.
+
+The second form of the function allows full access through SQL statements for
+updating records in the database. Write any valid SQL UPDATE statement and
+submit it to this function for execution. Sophisticated updates can be
+performed using the full power of the SQL dialect. The full SQL statement
+must have the exact syntax required by the driver/datasource for performing
+the update. This usually is in the form of:
+
+\begin{verbatim}
+ UPDATE tablename SET col1=X, col2=Y, ... where ...
+\end{verbatim}
+
+\wxheading{Parameters}
+
+\docparam{pSqlStmt}{Pointer to SQL UPDATE statement to be executed.}
+
+\wxheading{Remarks}
+
+A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
+this function to commit or rollback the update.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ wxString sqlStmt;
+ sqlStmt = "update PART set QTY = 0 where PART_NUMBER = '32'";
+\end{verbatim}
+
+\membersection{wxDbTable::UpdateWhere}\label{wxdbtableupdatewhere}
+
+\func{bool}{UpdateWhere}{\param{const wxString \&}{pWhereClause}}
+
+Performs updates to the base table of the wxDbTable object, updating only the
+rows which match the criteria specified in the {\it pWhereClause}.
+
+All columns that are bound to member variables for this wxDbTable instance
+that were defined with the "updateable" parameter set to true will be updated
+with the information currently held in the memory variable.
+
+\wxheading{Parameters}
+
+\docparam{pWhereClause}{Pointer to a valid SQL WHERE clause. Do not
+include the keyword 'WHERE'.}
+
+\wxheading{Remarks}
+
+Care should be used when updating columns that are part of indexes with
+this function so as not to violate an unique key constraints.
+
+A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
+\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
+this function to commit or rollback the update(s).
+
+\membersection{wxDbTable::Where}\label{wxdbtablewhere}
+
+\func{const wxString \&}{Where}{}
+
+\func{void}{Where}{\param{const wxString\& }{Where}}
+
+Accessor function for the private class member wxDbTable::where. Can be used
+as a synonym for \helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
+(the first form of this function) to return the current where clause or
+\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause} (the second form
+of this function) to set the where clause for this table instance.
+
+\wxheading{Parameters}
+
+\docparam{Where}{A valid SQL WHERE clause. Do not include the keyword 'WHERE'.}
+
+\wxheading{Return value}
+
+The first form of this function returns the current value of the wxDbTable
+member variable ::where.
+
+The second form of the function has no return value, as it will always set
+the where clause successfully.
+
+\wxheading{See also}
+
+\helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause},
+\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+
+\membersection{wxDbTable::operator $++$}\label{wxdbtableplusplus}
+
+\func{bool}{operator $++$}{\void}
+
+Synonym for \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
+
+\wxheading{See also}
+
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}
+
+\membersection{wxDbTable::operator $--$}\label{wxdbtableminusminus}
+
+\func{bool}{operator $--$}{\void}
+
+Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
+
+\wxheading{See also}
+
+\helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
+
+\section{\class{wxDbTableInf}}\label{wxdbtableinf}
+
+\begin{verbatim}
+ tableName[0] = 0;
+ tableType[0] = 0;
+ tableRemarks[0] = 0;
+ numCols = 0;
+ pColInf = NULL;
+\end{verbatim}
+
+Currently only used by \helpref{wxDb::GetCatalog}{wxdbgetcatalog} internally
+and \helpref{wxDbInf}{wxdbinf} class, but may be used in future releases for
+user functions. Contains information describing the table (Name, type, etc).
+A pointer to a wxDbColInf array instance is included so a program can create a
+\helpref{wxDbColInf}{wxdbcolinf} array instance (using
+\helpref{wxDb::GetColumns}{wxdbgetcolumns})
+to maintain all information about the columns of a table in one memory
+structure.
+
+Eventually, accessor functions will be added for this class
+
+See the \helpref{database classes overview}{odbcoverview} for
+an introduction to using the ODBC classes.
+
+\wxheading{Include files}
+
+<wx/db.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbTableInf::Initialize}\label{wxdbtableinfinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+\section{\class{wxDbGridColInfo}}\label{wxdbgridcolinfo}
+
+This class is used to define columns to be shown, names of the columns,
+order and type of data, when using \helpref{wxdbGridTableBase}{wxdbgridtablebase} to display
+a Table or query in a \helpref{wxGrid}{wxgrid}
+
+See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} for
+an introduction to using the wxDbGrid classes.
+
+\wxheading{Include files}
+
+<wx/dbgrid.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDbGridColInfo::wxDbGridColInfo}\label{wxdbgridcolinfoctor}
+
+\func{}{wxDbGridColInfo}{\param{int }{colNumber}, \param{wxString }{type},
+ \param{wxString }{title}, \param{wxDbGridColInfo *}{next}}
+
+Default constructor. See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
+see two different ways for adding columns.
+
+
+\wxheading{Parameters}
+
+\docparam{colNumber}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
+\docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
+ use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
+\docparam{title}{The column label to be used in the grid display}
+\docparam{next}{A pointer to the next wxDbGridColInfo structure if using one-step
+construction, NULL terminates the list. Use Null also if using two step construction.}
+See the database grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
+see two different ways for adding columns.
+
+\membersection{wxDbGridColInfo::\destruct{wxDbGridColInfo}}\label{wxdbgridcolinfodtor}
+
+\func{}{\destruct{wxDbGridColInfo}}{}
+
+Destructor.
+
+\membersection{wxDbGridColInfo::AddColInfo}\label{wxdbgridcolinfoaddcolinfo}
+
+\func{void}{AddColInfo}{\param{int }{colNumber},
+\param{wxString }{type}, \param{wxString }{title}}
+
+Use this member function for adding columns. See the database
+grid example in \helpref{wxDbGridTableBase}{wxdbgridtablebase} to
+see two different ways for adding columns.
+
+It is important to note that this class is merely a specifier to the \helpref{wxDbGridTableBase}{wxdbgridtablebase}
+constructor. Changes made to this datatype after the \helpref{wxDbGridTableBase}{wxdbgridtablebase} is called will
+not have any effect.
+
+\wxheading{Parameters}
+\docparam{colNumber}{Column number in the \helpref{wxDbTable}{wxdbtable} instance to be used (first column is 0).}
+\docparam{type}{Column type ,wxString specifying the grid name for the datatype in this column, or
+ use wxGRID\_VALUE\_DBAUTO to determine the type automatically from the \helpref{wxDbColDef}{wxdbcoldef} definition}
+\docparam{title}{The column label to be used in the grid display}
+
+\wxheading{Remarks}
+
+As wxDbTable must be defined with to have columns which match those to by a wxDbGridColInfo
+info structure as this is the structure which informs the grid of how you want to display your
+\helpref{wxDbTable}{wxdbtable}. If no datatype conversion or the referenced column number does not exist the
+the behavior is undefined.
+
+See the example at \helpref{wxDbGridColInfo::wxDbGridColInfo}{wxdbgridcolinfoctor}.
+
+\section{\class{wxDbGridTableBase}}\label{wxdbgridtablebase}
+
+You can view a database table in a grid using this class.
+
+If you are deriving your own wxDbTable subclass for your table , then you may consider
+overriding GetCol() and SetCol() to provide calculated fields. This does work but care should
+be taken when using wxDbGridTableBase in this way.
+
+The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable
+object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable
+when an new on is assigned or wxGridTableBase's destructor is called.
+However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true);
+is an error. If you need to requery an table object the preferred way is
+that the client keeps ownership.
+
+\wxheading{Derived From}
+
+\helpref{wxGridTableBase}{wxgridtablebase}
+
+\wxheading{Include files}
+
+<wx/dbgrid.h>
+
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // First step, let's define wxDbTable
+ int numColumns = 2;
+ wxDbTable *table = new wxDbTable (db, tblName, numColumns);
+ int int_var;
+ wxChar string_name[255];
+ table->SetColDef (0, "column 0", DB_DATA_TYPE_INTEGER, &int_var,
+ SQL_C_LONG, sizeof(int_var), true);
+ table->SetColDef (1, "column 1", DB_DATA_TYPE_VARCHAR, &string_name,
+ SQL_C_LONG, sizeof(string_name), false);
+
+ // now let's define columns in the grid
+
+ // first way to do it
+ wxDbGridColInfo *columns;
+ columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column",
+ new wxDbGridColInfo(1, wxGRID_VALUE_STRING, "second column",
+ NULL);
+
+ // second way to do it
+ wxDbGridColInfo *columns;
+ // first column is special
+ columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column", NULL);
+ // all the rest
+ columns->AddColInfo (1, wxGRID_VALUE_STRING, "second column");
+
+ // second way may be better when columns are not known at compile time
+
+ // now, let's open the table and make a Query()
+ table->Open();
+ // this step is very important
+ table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
+ // in the grid we will see only the rows of the result query
+ m_dbTable->Query();
+
+ wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, true);
+ delete columns; // not needed anymore
+ wxGrid *grid = new wxGrid ( ... );
+ grid->SetTable(dbgrid, true);
+ grid->Fit();
+\end{verbatim}
+
+
+\wxheading{Include files}
+
+<wx/dbgrid.h>
+
+\wxheading{Helper classes and data structures}
+
+\membersection{wxDbGridTableBase::wxDbGridTableBase}\label{wxdbgridtablebaseconstr}
+
+\func{}{wxDbGridTableBase}{\param{wxDbTable *}{tab}, \param{wxDbGridColInfo *}{ColInfo},
+ \param{int }{count = wxUSE\_QUERY}, \param{bool }{takeOwnership = true}}
+
+Constructor.
+
+\wxheading{Parameters}
+
+\docparam{tab}{ The database table you want to display. Must be opened and queried before display the grid.
+See the example \helpref{above}{wxdbgridtablebase}.}
+\docparam{ColInfo}{ Columns titles, and other values. See \helpref{wxDbGridColInfo}{wxdbgridcolinfo}.}
+\docparam{count}{You can use a query result set (wxUSE\_QUERY, to use wxDbTable::Count(wxDbTable::Count()
+ 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 }
+
+\docparam{takeOwnership}{ If true, this class deletes wxDbTable when it stops
+referring to it, if false application must
+take care of deleting it. }
+
+\membersection{wxDbGridTableBase::ValidateRow}\label{wxdbgridtablebasevalidate}
+
+\func{void}{ValidateRow}{\param{int }{row}}
+
+It ensures that the row data is fetched from the database, and it the wxDbTable local buffer,
+the row number passed should be the grid row.
+
+\wxheading{Parameters}
+
+\docparam{row}{ Row where validation must be done. }
+
+\membersection{wxDbGridTableBase::UpdateRow}\label{wxdbgridtablebaseupdaterow}
+
+\func{bool}{UpdateRow}{\param{int }{row}}
+
+If row has changed it forces that row to be written back to the database, however support
+for detecting whether insert/update is required is currently not in wxDbTable, so this
+function is currently unsupported.
+
+\wxheading{Parameters}
+
+\docparam{row}{ Row you want to update. }
+
+\membersection{wxDbGridTableBase::AssignDbTable}\label{wxdbgridtablebaseassigndbtable}
+
+\func{bool}{AssignDbTable}{\param{wxDbTable *}{tab},\param{int }{count = wxUSE\_QUERY},
+\param{bool }{takeOwnership = true}}
+
+Resets the grid for using with a new database table, but using the same columns definition.
+This can be useful when re-querying the database and want to see the changes.
+
+\wxheading{Parameters}
+
+\docparam{tab}{ Database table you want to assign to the grid. }
+\docparam{count}{ Number of rows you want to show or wxUSE\_QUERY for using a query. }
+\docparam{takeOwnership}{ If false, user must take care of deleting tab after deleting
+the wxDbGridTableBase. If true, deletion is made by destructor class. }
+
projects / wxWidgets.git / blobdiff