These are the databases currently tested and working with the ODBC classes. A call to \helpref{wxDb::Dbms}{wxdbdbms} will return one of these enumerated values listed below.
\begin{verbatim}
- dbmsUNIDENTIFIED,
- dbmsORACLE,
- dbmsSYBASE_ASA, // Adaptive Server Anywhere
- dbmsSYBASE_ASE, // Adaptive Server Enterprise
- dbmsMS_SQL_SERVER,
- dbmsMY_SQL,
- dbmsPOSTGRES,
- dbmsACCESS,
- dbmsDBASE,
+ dbmsUNIDENTIFIED
+ dbmsORACLE
+ dbmsSYBASE_ASA // Adaptive Server Anywhere
+ dbmsSYBASE_ASE // Adaptive Server Enterprise
+ dbmsMS_SQL_SERVER
+ dbmsMY_SQL
+ dbmsPOSTGRES
+ dbmsACCESS
+ dbmsDBASE
dbmsINFORMIX
+ dbmsVIRTUOSO
+ dbmsDB2
\end{verbatim}
See the remarks in \helpref{wxDb::Dbms}{wxdbdbms} for exceptions/issues with each of these database engines.
Default constructor.
-\func{}{wxDb}{\param{HENV\& }{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC_FWD_ONLY_CURSORS}}
+\func{}{wxDb}{\param{HENV &}{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC_FWD_ONLY_CURSORS}}
Constructor, used to create an ODBC connection to a data source.
\docparam{userID}{Database user name to use in accessing the database. All tables to which this user has rights will be evaluated in the catalog.}
-\docparam{fileName}{OPTIONAL argument. Name of the text file to create and write the DB catalog to.}
+\docparam{fileName}{{\it OPTIONAL}. Name of the text file to create and write the DB catalog to.}
\wxheading{Return value}
\end{verbatim}
+\membersection{wxDb::Dbms}\label{wxdbdbms}
+
+\func{wxDBMS }{Dbms}{\void}
+
+\wxheading{Remarks}
+
+The return value will be of the enumerated type wxDBMS. This enumerated
+type contains a list of all the currently tested and supported databases.
+
+Additional databases may be work with these classes, but these databases
+returned by this function have been tested and confirmed to work with
+these ODBC classes.
+
+enum wxDBMS includes:
+
+\begin{verbatim}
+ dbmsUNIDENTIFIED
+ dbmsORACLE
+ dbmsSYBASE_ASA
+ dbmsSYBASE_ASE
+ dbmsMY_SQL_SERVER
+ dbmsMY_SQL
+ dbmsPOSTGRES
+ dbmsACCESS
+ dbmsDBASE
+ dbmsINFORMIX
+\end{verbatim}
+
+There are known issues with conformance to the ODBC standards with several
+datasources listed above. Please see the overview for specific details on
+which datasource have which issues.
+
+\wxheading{Return value}
+
+The return value will indicate which of the supported datasources is
+currently connected to by this connection. In the event that the
+datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.
+
+
\membersection{wxDb::DispAllErrors}\label{wxdbdispallerrors}
\func{bool}{DispAllErrors}{\param{HENV}{ aHenv}, {\param}{HDBC}{ aHdbc = SQL_NULL_HDBC}, {\param}{HSTMT}{ aHstmt = SQL_NULL_HSTMT}}
-Logs all database errors that occurred as a result of the last executed database command. This logging also includes debug logging when compiled in debug mode via \helpref{wxLogDebug}{wxlogdebug}. If logging is turned on via \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, then an entry is also logged to the defined log file.
+Logs all database errors that occurred as a result of the last executed
+database command. This logging also includes debug logging when compiled in
+debug mode via \helpref{wxLogDebug}{wxlogdebug}. If logging is turned on
+via \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, then an entry is also
+logged to the defined log file.
\wxheading{Parameters}
\wxheading{Example}
\begin{verbatim}
- SDWORD cb;
- ULONG reqQty;
- wxString sqlStmt;
- sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
+ 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 this row of the result set and store 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);
+ // 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 this row of the result set and store 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 GetData must request the columns in ordinal
+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{char *}{GetDatabaseName}{\void}
+\func{const char *}{GetDatabaseName}{\void}
Returns the name of the database engine.
\membersection{wxDb::GetDataSource}\label{wxdbgetdatasource}
-\func{char *}{GetDataSource}{\void}
+\func{const char *}{GetDataSource}{\void}
Returns the ODBC datasource name.
\func{bool}{GetNext}{\void}
-Requests the next row in the result set obtained by issueing a query through a direct request using wxDb::ExecSql().
+Requests the next row in the result set obtained by issuing a query through a direct request using wxDb::ExecSql().
\wxheading{See also}
}
\end{verbatim}
+
\membersection{wxDb::GetPassword}\label{wxdbgetpassword}
-\func{char *}{GetPassword}{\void}
+\func{const char *}{GetPassword}{\void}
Returns the password used to connect to the datasource.
Returns the number of wxDbTable() instances currently using this data source connection.
+
\membersection{wxDb::GetUsername}\label{wxdbgetusername}
-\func{char *}{GetUsername}{\void}
+\func{const char *}{GetUsername}{\void}
Returns the user name used to access the datasource.
+
\membersection{wxDb::Grant}\label{wxdbgrant}
\func{bool}{Grant}{\param{int}{ privileges}, \param{char *}{tableName}, \param{char *}{userList = "PUBLIC"}}
\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_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}{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.}
\func{bool}{IsFwdOnlyCursors}{\void}
-Indicates whether this connection to the datasource only allows forward scrolling cursors or not. This state is set at connection creation time.
+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 forward only cursors, then even if
+the datasource and ODBC driver support backward scrolling cursors, then
+tables using this database connection can only 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 wxODBC_FWD_ONLY_CURSORS value. This default setting can be overridden
+when the wxDb connection is initially created (see \helpref{wxDb constructor}{wxdbconstr}).
+
+\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 capable
+of supporting backward scrolling cursors (see note above).
\wxheading{Remarks}
-Added as of wxWindows v2.4 release, this function is a renamed version of wxDb::FwdOnlyCursors() to match the normal wxWindows naming conventions for class member functions.
+Added as of wxWindows v2.4 release, this function is a renamed version of
+wxDb::FwdOnlyCursors() to match the normal wxWindows 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 wxWindows versions priori to 2.4.
\wxheading{See also}
-\helpref{wxDb::wxDb}{wxdbconstr}, \helpref{wxDbGetConnection}{wxdbfunctions}
+\helpref{wxDb constructor}{wxdbconstr}, \helpref{wxDbGetConnection}{wxdbfunctions}
+
\membersection{wxDb::IsOpen}\label{wxdbisopen}
\func{bool}{IsOpen}{\void}
-Indicates whether the database connection to the datasource is currently opened.
+Indicates whether the database connection to the datasource is currently
+opened.
+
+\wxheading{Remarks}
+
+This function may indicate that the database is open, but 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, but other functions which depend on the \helpref{wxDb::Open}{wxdbopen}
+to have completed correctly may not function as expected. 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 char *}{errMsg} \param{const char *}{SQLState=0}}
+
+\docparam{errMsg}{Free-form text to display describing the error to be logged.}
+\docparam{SQLState}{Native SQL state error}
+
+\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::Open}\label{wxdbopen}
\func{bool}{Open}{\param{char *}{Dsn}, \param{char *}{Uid}, \param{char *}{AuthStr}}
+\func{bool}{Open}{\param{wxDb *}{copyDb}}
+
+Opens a connection to the datasource, sets behaviors of all databases 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 that 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}
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 witht the Uid.}
-
-\wxheading{Remarks}
-
-After a wxDb instance is created, it must then be opened. When opening a data source, there must be hree pieces of information passed. The data source name, user name (ID) and the password for the user. No database activity on the data source can be performed until it is opened. This would normally be done at program startup and the data source would remain open for the duration of the program run. Note: It is possible to have multiple data sources open at the same time to support distributed database connections.
+\docparam{AuthStr}{The password associated with the Uid.}
+\docparam{copyDb}{Already completely configured and opened datasource
+connection from which all Dsn, Uid, AuthStr, and data typing information is
+to be copied from for use by this datasource connection.}
+
+\wxheading{Remarks}
+
+After a wxDb instance is created, it must then be opened. When opening a
+data source, there must be hree pieces of information passed. The data
+source name, user name (ID) and the password for the user. No database
+activity on the data source can be performed until it is opened. This
+would normally be done at program startup and the data source would remain
+open for the duration of the program run.
+
+It is possible to have multiple data sources open at the same time to
+support distributed database connections by having separate instances of wxDb
+objects that use 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 they can be successfully executed, but use of the datatypes
+that are normally determined during open will not be accessible to any
+wxDbTable objects using this connection.
\wxheading{Example}
\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 displayed) or FALSE (debug
+messages are not displayed.}
+
+\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 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}{wxdbconstr}
+
+
\membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
-\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxChar *}{filename = SQL_LOG_FILENAME}, \param{bool}{ append = FALSE}}
+\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxChar *}{filename = SQL_LOG_FILENAME}, \param{bool }{ append = FALSE}}
\wxheading{Parameters}
When called with {\it sqlLogOFF}, the logging file is closed, and any calls to WriteSqlLog() are ignored.
+
\membersection{wxDb::TableExists}\label{wxdbtablexists}
\func{bool}{TableExists}{\param{const char *}{tableName}, \param{const char *}{userID=NULL}, \param{const char *}{path=NULL}}
-Checks the ODBC data source 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).
+Checks the ODBC data source 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}
This function does not indicate whether or not the user has privileges to query or perform other functions on the table.
+\wxheading{See also}
+
+\helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
+
+
+\membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}
+
+\func{bool}{TablePrivileges}{\param{const char *}{tableName}, \param{const char *}{priv}, \param{const char *}{userID=NULL}, \param{const char *}{path=""}}
+
+Checks the ODBC data source 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 data source 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}{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. {\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}
+}
+\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 data source dependent.
+
+For example, the privilege UPDATE might allow the connected user to update
+all columns in a table on one data source, but only those columns for
+which the grantor (the user that granted the connected user) has the UPDATE
+privilege on another data source.
+
+
\membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}
\func{int}{TranslateSqlState}{\param{const wxChar *}{SQLState}}
Returns the internal class DB_ERR code. See \helpref{wxDb::DB_STATUS}{wxdb} definition.
+
\membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
\func{bool}{WriteSqlLog}{\param{const wxChar *}{logMsg}}
\helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
-\begin{comment} % George: this is a duplicate of one above (only with more text)
-\membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}
-
-\func{bool}{IsFwdOnlyCursors}{\void}
-
-\wxheading{Remarks}
-
-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 forward only cursors, then even if
-the datasource and ODBC driver support backward scrolling cursors, then
-tables using this database connection can only 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 wxODBC_FWD_ONLY_CURSORS value. This default setting can be overridden
-when the wxDb connection is initially created (see \helpref{wxDb constructor}{wxdbconstr}).
-
-\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 capable
-of supporting backward scrolling cursors (see note above).
-
-\wxheading{See also}
-
-\helpref{wxDb constructor}{wxdbconstr}
-\end{comment}
-\membersection{wxDb::Dbms}\label{wxdbdbms}
-
-\func{wxDBMS }{Dbms}{\void}
-
-\wxheading{Remarks}
-
-The return value will be of the enumerated type wxDBMS. This enumerated
-type contains a list of all the currently tested and supported databases.
+\section{\class{wxDbColDataPtr}}\label{wxdbcoldataptr}
-Additional databases may be work with these classes, but these databases
-returned by this function have been tested and confirmed to work with
-these ODBC classes.
+Pointer to dynamic column definitions for use with a wxDbTable instance.
+Currently there are no member functions for this class.
-enum wxDBMS includes:
\begin{verbatim}
- dbmsUNIDENTIFIED
- dbmsORACLE
- dbmsSYBASE_ASA
- dbmsSYBASE_ASE
- dbmsMY_SQL_SERVER
- dbmsMY_SQL
- dbmsPOSTGRES
- dbmsACCESS
- dbmsDBASE
- dbmsINFORMIX
+ void *PtrDataObj;
+ int SzDataObj;
+ int SqlCtype;
\end{verbatim}
-There are known issues with conformance to the ODBC standards with several
-datasources listed above. Please see the overview for specific details on
-which datasource have which issues.
-
-\wxheading{Return value}
-
-The return value will indicate which of the supported datasources is
-currently connected to by this connection. In the event that the
-datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.
-\membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
+\section{\class{wxDbColDef}}\label{wxdbcoldef}
-\func{void}{SetDebugErrorMessages}{\param{bool }{state}}
+This class is used to hold information about the columns bound to an
+instance of a wxDbTable object.
-\docparam{state}{Either TRUE (debug messages are displayed) or FALSE (debug
-messages are not displayed.}
+Each instance of this class describes one column in the wxDbTable
+object. When calling the \helpref{wxDb constructor}{wxdbconstr}, 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].
-\wxheading{Remarks}
+Currently there are no member functions for this class.
-Turns on/off debug error messages from the ODBC class library. When
-this function is passed TRUE, errors are reported to the user automatically
-in a text or pop-up dialog when an ODBC error occurs. When passed FALSE,
-errors are silently handled.
+Typically, \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs} takes care of
+populating an array of these data structures for the wxDbTable instance.
-When compiled in release mode (FINAL=1), this setting has no affect.
+\begin{verbatim}
+ char ColName[DB_MAX_COLUMN_NAME_LEN+1]; // Column Name
+ int DbDataType; - Logical Data Type; e.g. DB_DATA_TYPE_INTEGER
+ int 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{wxDb constructor}{wxdbconstr}
-
-\membersection{wxDb::LogError}\label{wxdblogerror}
-
-\func{void}{LogError}{\param{const char *}{errMsg} \param{const char *}{SQLState=0}}
-
-\docparam{errMsg}{Free-form text to display describing the error to be logged.}
-\docparam{SQLState}{Native SQL state error}
-
-\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{wxDbTable::GetColDefs}{wxdbtablegetcoldefs}, \helpref{wxDb constructor}{wxdbconstr}
-\helpref{wxDb::WriteSqlLog}{wxdbwritesqllog}
\section{\class{wxDbColInf}}\label{wxdbcolinf}
Used with the \helpref{wxDb::GetColumns}{wxdbgetcolumns} functions for obtaining all retrievable information about a columns definition.
+
\section{\class{wxDbColFor}}\label{wxdbcolfor}
Beginning support for handling international formatting specifically on dates and floats.
Work in progress, and should be inter-related with wxLocale
+
+\section{\class{wxDbIdxDef}}\label{wxdbidxdef}
+
+Used in creation of non-primary indexes. Currently there are no member
+functions for this class.
+
+\begin{verbatim}
+ char ColName[DB_MAX_COLUMN_NAME_LEN+1] - Name of column
+ bool Ascending - Are the values in the index in ASCENDING sequence?
+\end{verbatim}
+
+
\section{\class{wxDbInf}}\label{wxdbinf}
Contains information regarding the database connection (data source name,
information about all tables in the datasource to have all the datasource's
information in one memory structure.
+
\section{\class{wxDbTable}}\label{wxdbtable}
A wxDbTable instance provides re-usable access to rows of data in
\wxheading{Helper classes and data structures}
The following classes and structs are defined in dbtable.cpp/.h for use with the wxDbTable class.
-\begin{verbatim}
-
- class wxDbColDef : Bound column definitions for use by a wxDbTable
- instance
-
- class wxDbColDataPtr : Pointer to dynamic column definitions for use with
- a wxDbTable instance
-
- class wxDbIdxDef : Used in creation of non-primary indexes
-
-\end{verbatim}
+\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 Index number of the cursor that each table will use
by default.
\end{verbatim}
-\wxheading{Remarks}
-
\wxheading{See also}
\helpref{wxDbTable}{wxdbtable}
\membersection{wxDbTable::wxDbTable}\label{wxdbtableconstr}
-\func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const char *}{tblName}, \param{const int }{nCols},\param{const char *}{qryTblName = 0}, \param{bool}{qryOnly = !wxDB_QUERY_ONLY},\param{const char *}{tblPath=NULL}}
+\func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const char *}{tblName}, \param{const int }{nCols}, \param{const char *}{qryTblName = 0}, \param{bool }{qryOnly = !wxDB_QUERY_ONLY}, \param{const char *}{tblPath=NULL}}
Default constructor.
\wxheading{Parameters}
-\docparam{pSqlStmt}{}
-\docparam{typeOfDel}{}
-\docparam{pWhereClause}{Default is 0.}
-
+\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{nCols}{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 many joins. Default is 0 (NULL)}
+\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 data sources (such as dBase)
+require a path to where the table is stored on the system. Default is NULL.}
\membersection{wxDbTable::wxDbTable}\label{wxdbtabledestr}
\membersection{wxDbTable::BuildDeleteStmt}\label{wxdbtablebuilddeletestmt}
-\func{void}{BuildSelectStmt}{\param{char *}{pSqlStmt}, \param{int }{typeOfDel}, \param{const char *}{pWhereClause=0}}
+\func{void}{BuildDeleteStmt}{\param{char *}{pSqlStmt}, \param{int }{typeOfDel}, \param{const char *}{pWhereClause=0}}
+
+Constructs the full SQL statement that can be used to delete all rows matching
+the criteria in the pWhereClause.
\wxheading{Parameters}
-\docparam{pSqlStmt}{}
-\docparam{typeOfDel}{}
-\docparam{pWhereClause}{Default is 0.}
+\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{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 0 (NULL).}
+
+\wxheading{Remarks}
+
+This member function allows you to see what the SQL DELETE 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 in \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
\membersection{wxDbTable::BuildSelectStmt}\label{wxdbtablebuildselectstmt}
\func{void}{BuildSelectStmt}{\param{char *}{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. Internal to the wxDbTable class, this
+function is called 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}{}
-\docparam{typeOfSelect}{}
-\docparam{distinct}{}
+\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 allows you to see what the SQL SELECT 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 in \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
\membersection{wxDbTable::BuildUpdateStmt}\label{wxdbtablebuildupdatestmt}
\func{void}{BuildSelectStmt}{\param{char *}{pSqlStmt}, \param{int }{typeOfUpd}, \param{const char *}{pWhereClause=0}}
+Constructs the full SQL statement that can be used to update all rows matching
+the criteria in the pWhereClause.
+
+If typeOfUpd 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 data source 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}{}
-\docparam{typeOfUpd}{}
-\docparam{pWhereClause}{Default is 0.}
+\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{typeOfUpd}{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 typeOfUpd is DB_UPD_WHERE,
+then you must also pass in a SQL WHERE clause in this argument. Default
+is 0 (NULL).}
+
+\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 in \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
+this function.
\membersection{wxDbTable::BuildWhereStmt}\label{wxdbtablebuildwherestmt}
\func{void}{BuildSelectStmt}{\param{char *}{pWhereClause}, \param{int }{typeOfWhere}, \param{const char *}{qualTableName=0}, \param{const char *}{useLikeComparison=FALSE}}
+Constructs the portion of a SQL statement which would follow the word 'WHERE'
+in the SQL statement to be passed to the data source. The returned string
+does NOT include the word 'WHERE'.
+
\wxheading{Parameters}
-\docparam{pWhereClause}{}
-\docparam{typeOfWhere}{}
-\docparam{qualTableName}{Default is 0.}
-\docparam{useLikeComparison}{Default is FALSE.}
+\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 0
+(NULL).}
+\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 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 data source supports SELECT ... FOR UPDATE.
+When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement,
+all records retrieved from the query are locked.
+
\wxheading{Remarks}
+Not all data sources support the "FOR UPDATE" clause, so you must use this
+member function to determine if the data source currently connected to supports
+this behavior or not before trying to select using "FOR UPDATE".
+
\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 data store 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.
+
+This is always handled by the class library except in the case of
+QueryBySqlStatement(). 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 data source or not.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ wxDbTable parts;
+ .....
+ if (parts.CanUpdByROWID())
+ begin
+ // Note that the ROWID column must always be the last column selected
+ sqlStmt = "SELECT PART_NO, PART_DESC, ROWID" FROM PARTS";
+ end
+ else
+ sqlStmt = "SELECT PART_NO, PART_DESC" FROM PARTS";
+\end{verbatim}
+
\membersection{wxDbTable::ClearMemberVars}\label{wxdbtableclearmembervars}
\func{void}{ClearMemberVars}{\void}
+Initializes all of the bound columns of the wxDbTable instance to zero.
+In the case of a string, zero is copied to the first byte of the string.
+
\wxheading{Remarks}
+This is useful before calling \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}{}
+\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.
+
\membersection{wxDbTable::Count}\label{wxdbtablecount}
\func{ULONG}{Count}{\param{const char *}{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}{Default is "*".}
+\docparam{args}{{\it OPTIONAL}. This arguement 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 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().
+
+\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 char *}{idxName}, \param{bool}{unique}, \param{int }{noIdxCols}, \param{wxDbIdxDef *}{pIdxDefs}, \param{bool }{attemptDrop=TRUE}}
+\func{bool}{CreateIndex}{\param{const char *}{idxName}, \param{bool }{unique}, \param{int }{noIdxCols}, \param{wxDbIdxDef *}{pIdxDefs}, \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{idxName}{}
-\docparam{unique}{}
-\docparam{noIdxCols}{}
-\docparam{pIdxDefs}{}
-\docparam{attemptDrop}{Default is TRUE.}
+\docparam{idxName}{Name of the Index. Name must be unique within the table space of the datasource.}
+\docparam{unique}{Indicates if this index is unique.}
+\docparam{noIdxCols}{Number of columns in the index.}
+\docparam{pIdxDefs}{A pointer to an array 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. PARTS_IDX1). 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 controlling whether duplicates cannot be
+inserted into the table for unique indices.
+
+In the third parameter, specify how many columns are in your index. This
+number must match the number of columns defined in the 'pIdxDefs' parameter.
+
+The fourth parameter specifies which columns make up the index using the
+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 wxDbIdxDef structure.
+
+The fifth parameter is provided as many datasources will not automatically
+overwrite existing indexes with the same name. They 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, this function will modify the column
+definition to change the column to be NOT NULL.
+
+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 idxDef[2]; // 2 columns make up the index
+
+ strcpy(idxDef[0].ColName, "PART_DESC"); // Column 1
+ idxDef[0].Ascending = TRUE;
+
+ strcpy(idxDef[1].ColName, "SERIAL_NO"); // Column 2
+ idxDef[1].Ascending = FALSE;
+
+ // Create a name for the index based on the table's name
+ wxString indexName;
+ indexName.sprintf("%s_IDX1",parts->GetTableName());
+ parts->CreateIndex(indexName.c_str(), TRUE, 2, idxDef);
+\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}{Default is TRUE.}
+\docparam{attemptDrop}{{\it OPTIONAL}. Default is TRUE.}
\wxheading{Remarks}
-\membersection{wxDbTable::DB_STATUS}\label{wxdbtabledbstatus}
+This function creates the table and primary index (if any) in the table space
+associated with the connected data source. 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 for that user.
-\func{bool}{DB_STATUS}{\void}
+In your derived wxDbTable object constructor, the columns and primary index
+of the table are described through the 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.
-Accessor function for the private member variable DB_STATUS.
+It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
+after executing this function.
-\membersection{wxDbTable::IsColNull}\label{wxdbtableiscolnull}
-\func{bool}{IsColNull}{\param{int }{colNo}}
+\membersection{wxDbTable::DB_STATUS}\label{wxdbtabledbstatus}
-\wxheading{Parameters}
+\func{bool}{DB_STATUS}{\void}
-\docparam{colNo}{}
+Accessor function that returns the wxDb private member variable DB_STATUS for
+the database connection used by this instance of wxDbTable.
-\wxheading{Remarks}
\membersection{wxDbTable::Delete}\label{wxdbtabledelete}
\func{bool}{Delete}{\void}
+Deletes the current record from the data source.
+
\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}}
+\func{bool}{DeleteCursor}{\param{HSTMT *}{hstmtDel}}
+
+Allows a program to delete a cursor.
\wxheading{Parameters}
-\docparam{hstmtDel}{}
+\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.
+
+
+\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 to match in the columns to match on.
\wxheading{Remarks}
+To delete all users with a first name of "JOHN", do the following:
+
+\begin{verbatim}
+ 1) Clear all "columns" using \helpref{wxDbTable::ClearMemberVars}{wxdbtableclearmembervars}.
+ 2) Set the FIRST_NAME column equal to "JOHN".
+ 3) Call \helpref{wxDbTable::DeleteMatching}{wxdbtabledeletematching}.
+\end{verbatim}
+
+The WHERE clause is built by the ODBC class library based on all non-zero
+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 scrolling through the records locking each as you go. After the
+row(s) have been successfully locked, call this function.
+
+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.
+
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample to delete all users with a first name
+ // of "JOHN"
+ users.ClearMemberVars();
+ strcpy(users.FirstName,"JOHN");
+ users.DeleteMatching();
+\end{verbatim}
+
+
\membersection{wxDbTable::DeleteWhere}\label{wxdbtabledeletewhere}
\func{bool}{DeleteWhere}{\param{const char *}{pWhereClause}}
+Deletes all rows from the table which match the criteria specified in the
+WHERE clause that is passed in as the sole parameter.
+
\wxheading{Parameters}
-\docparam{pWhereClause}{}
+\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}
-\membersection{wxDbTable::DeleteMatching}\label{wxdbtabledeletematching}
+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.
-\func{bool}{DeleteMatching}{\void}
+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.
+
+\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}
-\wxheading{Remarks}
\membersection{wxDbTable::DropIndex}\label{wxdbtabledropindex}
\func{bool}{DropIndex}{\param{const char *}{idxName}}
+Allows an index on the associated table to be dropped (deleted) if the user
+login has sufficient privileges to do so.
+
\wxheading{Parameters}
-\docparam{idxName}{}
+\docparam{idxName}{Name of the index to be dropped.}
\wxheading{Remarks}
+If the index specified in the 'idxName' 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.
+
+Some 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 char *}{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 outer
+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.
+
+\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.
+Accessor function for the private member variable pDb which is a pointer to
+the datasource connection that this wxDbTable instance uses.
-\wxheading{Remarks}
\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.
+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::FwdOnlyCursors}{wxdbfwdonlycursors}
+
\membersection{wxDbTable::GetFromClause}\label{wxdbtablegetfromclause}
\func{const char *}{GetFromClause}{}
-Accessor function that returns the current FROM setting assigned with the \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause}.
+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.
+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::FwdOnlyCursors}{wxdbfwdonlycursors}
+
\membersection{wxDbTable::GetNewCursor}\label{wxdbtablegetnewcursor}
\func{HSTMT *}{GetNewCursor}{\param{bool }{setCursor=FALSE}, \param{bool }{bindColumns=TRUE}}
+\begin{comment}
+% George: @@@@@@@@STILL TO DO
+\end{comment}
+
\wxheading{Parameters}
-\docparam{setCursor}{Default is FALSE.}
-\docparam{bindColumns}{Default is TRUE.}
+\docparam{setCursor}{{\it OPTIONAL}. Default is FALSE.}
+\docparam{bindColumns}{{\it OPTIONAL}. Default is TRUE.}
\wxheading{Remarks}
+
\membersection{wxDbTable::GetNext}\label{wxdbtablegetnext}
\func{bool}{GetNext}{\void}
-\wxheading{Remarks}
+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{See also}
+\helpref{wxDbTable::++}{wxdbtableplusplus}
\membersection{wxDbTable::GetNumberOfColumns}\label{wxdbtablegetnumberofcolumns}
\func{bool}{GetNumberOfColumns}{}
-Accessor function that returns the number of columns that are statically bound for access by the wxDbTable instance.
+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 char *}{GetOrderByClause}{}
-Accessor function that returns the current ORDER BY setting assigned with the \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}.
+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.
+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::FwdOnlyCursors}{wxdbfwdonlycursors}
+\helpref{wxDb::FwdOnlyCursors}{wxdbfwdonlycursors},
+\helpref{wxDbTable::--}{wxdbtableminusminus}
\membersection{wxDbTable::GetQueryTableName}\label{wxdbtablegetquerytablename}
\func{const char *}{GetQueryTableName}{}
-\wxheading{Remarks}
+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.
+
+
\membersection{wxDbTable::GetTableName}\label{wxdbtablegettablename}
\func{const char *}{GetTableName}{}
-\wxheading{Remarks}
+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 char *}{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 char *}{GetWhereClause}{}
-Accessor function that returns the current WHERE setting assigned with the \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
+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
+ strcpy(parts->PartName, "10");
+ strcpy(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{int }{colNo}}
+
+Used primarily in the ODBC class library to determine if a column is equal
+to "NULL". Works for all data types supported by the ODBC class library.
+
+\wxheading{Parameters}
+
+\docparam{colNo}{The column number of the bound column as defined by the
+\helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}
+calls which defined the columns accesible to this wxDbTable instance.}
+
\wxheading{Remarks}
+NULL column support is currently not fully implemented as of wxWindows 2.4
+
+
\membersection{wxDbTable::IsCursorClosedOnCommit}\label{wxdbtableiscursorclosedoncommit}
\func{bool}{IsCursorClosedOnCommit}{\void}
-\wxheading{Remarks}
+Accessor function to return information collected during the opening of the
+datasource connection that is used by this wxDbTable instance.
+
+\wxheading{Return value}
+
+Returns TRUE if the cursor associated with this wxDbTable object is closed
+after a commit or rollback operation. Returns FALSE otherwise.
+
\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.
+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}{\void}
+Every wxDbTable instance must be opened before it can be used. This function
+checks for the existence of the requested table, binds columns to the
+internal cursors needed (insert/update/select) and constructs the insert
+statement that is used for inserting data to the columns of a new row in
+the datasource.
+
\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
+sufficent 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
+return results as to why a table cannot be opened.
+
+\wxheading{See also}
+
+\helpref{wxDb::TableExists}{wxdbtableexists}, \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
+
+
+\membersection{wxDbTable::OrderBy}\label{wxdbtableorderby}
+
+\func{const char *}{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 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.COLUMN).}
+
+\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}}
+\func{virtual bool}{Query}{\param{bool }{forUpdate=FALSE}, \param{bool }{distinct=FALSE}}
\wxheading{Parameters}
-\docparam{forUpdate}{Default is FALSE.}
-\docparam{distinct}{Default is FALSE.}
+\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}
+
+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 outer
+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 record set after the query. To retrieve the first record, call
+\helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
+\helpref{wxDbTable::GetNext}{wxdbtablegetnext}. Typically, no data from the
+result set is returned to the client driver until a request to 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.
+
+The wxDbTable::Query() function is defined as "virtual" so that it may be
+overridden for application specific purposes.
+
+\normalbox{Be sure and set the wxDbTable's "where", "orderBy", and "from"
+member variables to "" if they are not being 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}
-\wxheading{Remarks}
\membersection{wxDbTable::QueryBySqlStmt}\label{wxdbtablequerybysqlstmt}
\func{bool}{QueryBySqlStmt}{\param{const char *}{pSqlStmt}}
+Performs a query against the datasource by accepting and passing verbatim the
+SQL SELECT statement passed to the function.
+
\wxheading{Parameters}
-\docparam{pSqlStmt}{}
+\docparam{pSqlStmt}{A 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 data source. 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{verbatim}
+ 1. 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.
+
+ 2. The columns must be returned in the same sequence as specified
+ when defining the bounds columns using wxDbTable::SetColDefs(), 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%).
+
+ 3. The ROWID can be included in your SELECT statement as the last column
+ selected, if the datasource supports it. Use wxDbTable::CanUpdByROWID()
+ 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{verbatim}
+
+Even though data can be selected from multiple tables in your select
+statement (joins), 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 through the \helpref{wxDbTable::Update}{wxdbtableupdate}
+function. 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
+ strcpy(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_no, 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_no, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
+ from parts
+ where warehouse = 10
+ order by part_no 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}}
+\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}{Default is FALSE.}
-\docparam{distinct}{Default is FALSE.}
+\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}.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ parts->ClearMemberVars(); // Set all columns to zero
+ strcpy(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}}
+\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}{Default is FALSE.}
-\docparam{distinct}{Default is FALSE.}
+\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}.
+
+\wxheading{Example}
+
+\begin{verbatim}
+ // Incomplete code sample
+ strcpy(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}
+Refreshes (re-reads into the bound columns) the current record for the
+current active cursor of the wxDbTable object.
+
+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{void}{SetColDefs}{\param{int }{index}, \param{const char *}{fieldName}, \param{int }{dataType}, \param{void *}{pData}, \param{int }{cType}, \param{int }{size}, \param{bool }{keyField = FALSE}, \param{bool }{upd = TRUE}, \param{bool }{insAllow = TRUE}, \param{bool }{derivedCol = FALSE}}
\wxheading{Parameters}
-\docparam{index}{}
-\docparam{fieldName}{}
-\docparam{dataType}{}
-\docparam{pData}{}
-\docparam{cType}{}
-\docparam{size}{}
-\docparam{keyField}{Default is FALSE.}
-\docparam{upd}{Default is TRUE.}
-\docparam{insAllow}{Default is TRUE.}
-\docparam{derivedCol}{Default is FALSE.}
+\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:}
-\docparam{colInfs}{}
-\docparam{numCols}{}
+\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
+\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 // strings
+ 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{upd}{{\it OPTIONAL}. Are updates allowed on this column?
+Default is TRUE.}
+\docparam{insAllow}{{\it OPTIONAL}. Inserts allowed on this column?
+Default is TRUE.}
+\docparam{derivedCol}{{\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}.
+
+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
+ strcpy(colDefs[0].ColName, "PART_NO");
+ colDefs[0].DbDataType = DB_DATA_TYPE_VARCHAR;
+ colDefs[0].PtrDataObj = PartNumber;
+ colDefs[0].SqlCtype = SQL_C_CHAR;
+ 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_NUMBER", DB_DATA_TYPE_VARCHAR, PartNumber,
+ SQL_C_CHAR, PART_NUMBER_LEN, TRUE, FALSE,TRUE,FALSE);
+\end{verbatim}
+
+
\membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
\func{bool}{Open}{\param{HSTMT *}{hstmtActivate = (void **) wxDB_DEFAULT_CURSOR}}
\wxheading{Parameters}
-\docparam{hstmtActivate}{Default is wxDB_DEFAULT_CURSOR.}
+\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
+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}}
+\func{void}{SetFromClause}{\param{const wxString &}{From}}
+
+Accessor function for setting the private class member wxDbTable::from
+that indicates what other tables should be outer 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}{}
+\docparam{From}{A comma separated list of table names that are to be outer
+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 outer
+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
+ // outer joined to the "PART" table via the 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::SetWhereClause}{wxdbtablesetwhereclause}
+
\membersection{wxDbTable::SetNull}\label{wxdbtablesetnull}
\func{bool}{SetNull}{\param{const char *}{colName}}
+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{colNo}{}
-\docparam{colName}{}
+\docparam{colNo}{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.}
\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}}
+\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.
+
+Synonym to this function is one form of \helpref{wxDbTable::OrderBy}{wxdbtableorderby}
\wxheading{Parameters}
-\docparam{OrderBy}{}
+\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.COLUMN).}
+
+\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::SetFromClause}{wxdbtablesetfromclause}
+
\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}{}
+\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}}
+\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.
+
+Synonym to this function is one form of \helpref{wxDbTable::Where}{wxdbtablewhere}
\wxheading{Parameters}
-\docparam{Where}{}
+\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.COLUMN).}
+
+\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 outer 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}
+
\membersection{wxDbTable::Update}\label{wxdbtableupdate}
\func{bool}{Update}{\param{const char *}{pSqlStmt}}
+This member function
+
+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}{}
+\docparam{pSqlStmt}{Pointer to SQL UPDATE statement to be executed.}
\wxheading{Remarks}
+Note that using this function when it is associated with the table that the
+wxDbTable instance is associated with does not prevent updating
+columns in any other table in the database for which the connected user
+has update privileges on. Constructing the appropriate full SQL statement,
+columns in other tables can also be updated as well.
+
+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}
+ strcpy(sqlStmt, "update PART set QTY = 0 where PART_NUMBER = '32'");
+\end{verbatim}
+
+
\membersection{wxDbTable::UpdateWhere}\label{wxdbtableupdatewhere}
\func{bool}{UpdateWhere}{\param{const char *}{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}{}
+\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::operator $++$}\label{wxdbtableplusplus}
\func{bool}{operator $++$}{\void}
-Same as \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
+Synonym for \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
\wxheading{See also}
\helpref{wxDbTable::GetNext}{wxdbtablegetnext}
+
\membersection{wxDbTable::operator $--$}\label{wxdbtableminusminus}
\func{bool}{operator $--$}{\void}
-Same as \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
+Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
\wxheading{See also}
\helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
+
\section{\class{wxDbTableInf}}\label{wxdbtableinf}
Currently only used by wxDb::GetCatalog() internally and wxDbInf class,
projects / wxWidgets.git / commitdiff
