datasource, as well as allowing access to any tables/views defined in
the datasource to which the user has sufficient privileges.
-
\wxheading{Include files}
<wx/db.h>
-
\wxheading{Helper classes and data structures}
The following classes and structs are defined in db.cpp/.h for use with the wxDb class.
\item \helpref{wxDbInf}{wxdbinf}
\end{itemize}
-
\wxheading{Constants}
-NOTE: In a future release, all ODBC class constants will be prefaced with 'wx'
+NOTE: In a future release, all ODBC class constants will be prefaced with 'wx'.
\begin{verbatim}
-
wxDB_PATH_MAX Maximum path length allowed to be passed to
the ODBC driver to indicate where the data
file(s) are located.
data type
\end{verbatim}
-
\subsection{Enumerated types}\label{wxdbenumeratedtypes}
+
\wxheading{Enumerated types}
\docparam{enum {\bf wxDbSqlLogState}}{sqlLogOFF, sqlLogON}
request
\end{verbatim}
-\docparam{wxChar {\bf wxDb::errorList}[DB_MAX_ERROR_HISTORY][DB_MAX_ERROR_MSG_LEN]}{The last n ODBC errors that have occurred on this database connection.}
+\docparam{wxChar {\bf wxDb::errorList}[DB\_MAX\_ERROR\_HISTORY][DB\_MAX\_ERROR\_MSG\_LEN]}{The last n ODBC errors that have occurred on this database connection.}
-\docparam{wxChar {\bf wxDb::errorMsg}[SQL_MAX_MESSAGE_LENGTH]}{This member variable is populated as a result of calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}. It contains the ODBC error message text.}
+\docparam{wxChar {\bf wxDb::errorMsg}[SQL\_MAX\_MESSAGE\_LENGTH]}{This member variable is populated as a result of calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}. It contains the ODBC error message text.}
\docparam{SDWORD {\bf wxDb::nativeError}}{Set by wxDb::DispAllErrors,
wxDb::GetNextError, and wxDb::DispNextError. It contains the
\wxheading{Remarks}
-Default cursor scrolling is defined by wxODBC_FWD_ONLY_CURSORS in setup.h
+Default cursor scrolling is defined by wxODBC\_FWD\_ONLY\_CURSORS in setup.h
when the wxWindows library is built. This behavior can be overridden when
an instance of a wxDb is created (see \helpref{wxDb constructor}{wxdbconstr}).
Default setting of this value TRUE, as not all databases/drivers support
The following functions are used in conjunction with the wxDb class.
+\func{void}{wxDbCloseConnections}{\void}
+
+\wxheading{Remarks}
+
+Closes all cached connections that have been made through use of the
+\helpref{wxDbGetConnection}{wxdbfunctions} function.
+
+NOTE: These connections are closed regardless of whether they are in use
+or not. This function should only be called after the program has
+finished using the connections and all wxDbTable instances that use any of
+the connections have been closed.
+
+This function performs a \helpref{wxDb::CommitTrans}{wxdbcommittrans}
+on the connection before closing it to commit any changes that are still
+pending, as well as to avoid any function sequence errors upon closing
+each connection.
+
+
+\func{int }{wxDbConnectionsInUse}{\void}
+
+\wxheading{Remarks}
+
+Returns a count of how many database connections are currently free ( not
+being used) that have been cached through use of the \helpref{wxDbGetConnection}{wxdbfunctions}
+function.
+
+
+\func{bool}{wxDbFreeConnection}{\param{wxDb *}{pDb}}
+
+\wxheading{Remarks}
+
+Searches the list of cached database connections connection for one matching
+the passed in wxDb instance. If found, that cached connection is freed.
+
+Freeing a connection means that it is marked as available (free) in the
+cache of connections, so that a call to \helpref{wxDbGetConnection}{wxdbfunctions}
+is able to return a pointer to the wxDb instance for use. Freeing a
+connection does NOT close the connection, it only makes the connection
+available again.
+
+
\func{wxDb *}{wxDbGetConnection}{\param{wxDbConnectInf *}{pDbConfig},
-\param{bool }{FwdOnlyCursors=(bool)wxODBC_FWD_ONLY_CURSORS}}
+\param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}
\wxheading{Remarks}
cached connections created by calls to wxDbGetConnection().
-\func{bool}{wxDbFreeConnection}{\param{wxDb *}{pDb}}
-
-\wxheading{Remarks}
-
-Searches the list of cached database connections connection for one matching
-the passed in wxDb instance. If found, that cached connection is freed.
-
-Freeing a connection means that it is marked as available (free) in the
-cache of connections, so that a call to \helpref{wxDbGetConnection}{wxdbfunctions}
-is able to return a pointer to the wxDb instance for use. Freeing a
-connection does NOT close the connection, it only makes the connection
-available again.
-
-
-\func{void}{wxDbCloseConnections}{\void}
-
-\wxheading{Remarks}
-
-Closes all cached connections that have been made through use of the
-\helpref{wxDbGetConnection}{wxdbfunctions} function.
-
-NOTE: These connections are closed regardless of whether they are in use
-or not. This function should only be called after the program has
-finished using the connections and all wxDbTable instances that use any of
-the connections have been closed.
-
-This function performs a \helpref{wxDb::CommitTrans}{wxdbcommittrans}
-on the connection before closing it to commit any changes that are still
-pending, as well as to avoid any function sequence errors upon closing
-each connection.
-
+\func{const wxChar *}{wxDbLogExtendedErrorMsg}{\param{const wxChar *}{userText}, \param{wxDb *}{pDb}, \param{wxChar *}{ErrFile}, \param{int }{ErrLine}}
-\func{int }{wxDbConnectionsInUse}{\void}
+Writes a message to the wxLog window (stdout usually) when an internal
+error situation occurs. This function only works in DEBUG builds
-\wxheading{Remarks}
-Returns a count of how many database connections are currently free ( not
-being used) that have been cached through use of the \helpref{wxDbGetConnection}{wxdbfunctions}
-function.
-
-
-\func{bool}{wxDbSqlLog}{\param{wxDbSqlLogState }{state}, \param{const wxString &}{filename = SQL_LOG_FILENAME}}
+\func{bool}{wxDbSqlLog}{\param{wxDbSqlLogState }{state}, \param{const wxString &}{filename = SQL\_LOG\_FILENAME}}
\wxheading{Remarks}
This function sets the sql log state for all open wxDb objects
-\func{bool}{wxDbGetDataSource}{\param{HENV }{henv}, \param{wxChar *}{Dsn}, \param{SWORD }{DsnMax}, \param{wxChar *}{DsDesc}, \param{SWORD }{DsDescMax}, \param{UWORD }{direction = SQL_FETCH_NEXT}}
+\func{bool}{wxDbGetDataSource}{\param{HENV }{henv}, \param{wxChar *}{Dsn}, \param{SWORD }{DsnMax}, \param{wxChar *}{DsDesc}, \param{SWORD }{DsDescMax}, \param{UWORD }{direction = SQL\_FETCH\_NEXT}}
\wxheading{Remarks}
wxStringList strList;
- while (wxDbGetDataSource(DbConnectInf.GetHenv(), Dsn, SQL_MAX_DSN_LENGTH+1, DsDesc, 255))
+ while (wxDbGetDataSource(DbConnectInf.GetHenv(), Dsn, SQL\_MAX\_DSN\_LENGTH+1, DsDesc, 255))
strList.Add(Dsn);
Default constructor.
-\func{}{wxDb}{\param{const HENV &}{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC_FWD_ONLY_CURSORS}}
+\func{}{wxDb}{\param{const HENV &}{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}
Constructor, used to create an ODBC connection to a datasource.
\membersection{wxDb::Catalog}\label{wxdbcatalog}
\func{bool}{Catalog}{\param{wxChar *}{ userID}, \param{const wxString &}{fileName =
-SQL_CATALOG_FILENAME}}
+SQL\_CATALOG\_FILENAME}}
Allows a data "dictionary" of the datasource to be created, dumping pertinent
information about all data tables to which the user specified in userID has
tables to which this user has rights will be evaluated in the catalog.}
\docparam{fileName}{{\it OPTIONAL}. Name of the text file to create and write
-the DB catalog to. Default is SQL_CATALOG_FILENAME.}
+the DB catalog to. Default is SQL\_CATALOG\_FILENAME.}
\wxheading{Return value}
\wxheading{Parameters}
-\docparam{viewName}{The name of the view. e.g. PARTS_V}
+\docparam{viewName}{The name of the view. e.g. PARTS\_V}
\docparam{colList}{{\it OPTIONAL} Pass in a comma delimited list of column
names if you wish to explicitly name each column in the result set. If not
\membersection{wxDb::DispAllErrors}\label{wxdbdispallerrors}
\func{bool}{DispAllErrors}{\param{HENV}{ aHenv}, {\param}{HDBC}
-{ aHdbc = SQL_NULL_HDBC}, {\param}{HSTMT}{ aHstmt = SQL_NULL_HSTMT}}
+{ aHdbc = SQL\_NULL\_HDBC}, {\param}{HSTMT}{ aHstmt = SQL\_NULL\_HSTMT}}
Used to log all database errors that occurred as a result of an executed
database command. This logging is automatic and also includes debug logging
\membersection{wxDb::GetColumns}\label{wxdbgetcolumns}
-\func{wxDbColInf *}{GetColumns}{\param{const wxString &}{tableName}, \param{int *}{numCols}, \param{const wxChar *}{userID=NULL}}
+\func{wxDbColInf *}{GetColumns}{\param{const wxString &}{tableName}, \param{UWORD *}{numCols}, \param{const wxChar *}{userID=NULL}}
\func{wxDbColInf *}{GetColumns}{\param{wxChar *}{tableName[]}, \param{const wxChar *}{userID}}
\wxheading{Parameters}
\docparam{tableName}{The table name you wish to obtain column information about.}
-\docparam{numCols}{Pointer to an integer which will hold a count of the number of columns returned by this function}
+\docparam{numCols}{Pointer to a UWORD which will hold a count of the number of columns returned by this function}
\docparam{tableName[]}{An array of pointers to table names you wish to obtain column information about. The last element of this array must be a NULL string.}
\docparam{userID}{Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. {\it userID} is evaluated in the following manner:}
passed for this parameter, as the API knows the size of the expected return
value.}
\docparam{cbReturned}{Pointer to the buffer containing the length of the
-actual data returned. If this value comes back as SQL_NULL_DATA, then the
+actual data returned. If this value comes back as SQL\_NULL\_DATA, then the
\helpref{wxDb::GetData}{wxdbgetdata} call has failed.}
\wxheading{See also}
\membersection{wxDb::GetKeyFields}\label{wxdbgetkeyfields}
-\func{int }{GetKeyFields}{\param{const wxString &}{tableName}, \param{wxDbColInf *}{colInf}, \param{int }{nocols}}
+\func{int }{GetKeyFields}{\param{const wxString &}{tableName}, \param{wxDbColInf *}{colInf}, \param{UWORD }{nocols}}
Used to determine which columns are members of primary or non-primary indexes on the specified table. If a column is a member of a foreign key for some other table, that information is detected also.
\membersection{wxDb::GetNextError}\label{wxdbgetnexterror}
\func{bool}{GetNextError}{\param{HENV}{ aHenv},
-\param{HDBC}{ aHdbc = SQL_NULL_HDBC}, \param{HSTMT}{ aHstmt = SQL_NULL_HSTMT}}
+\param{HDBC}{ aHdbc = SQL\_NULL\_HDBC}, \param{HSTMT}{ aHstmt = SQL\_NULL\_HSTMT}}
\wxheading{Parameters}
\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
+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}
The default setting of whether a wxDb connection to a database allows
forward-only or also backward scrolling cursors is defined in setup.h by the
-value of wxODBC_FWD_ONLY_CURSORS. This default setting can be overridden
+value of wxODBC\_FWD\_ONLY\_CURSORS. This default setting can be overridden
when the wxDb connection is initially created (see
\helpref{wxDb constructor}{wxdbconstr} and \helpref{wxDbGetConnection}{wxdbfunctions}).
\docparam{tableName}{Name of the table that the column to be modified is in.}
\docparam{columnName}{Name of the column to be modified. NOTE: Name of column cannot
be changed with this function.}
-\docparam{dataType}{Any one of DB_DATA_TYPE_VARCHAR, DB_DATA_TYPE_INTEGER,
-DB_DATA_TYPE_FLOAT, DB_DATA_TYPE_DATE.}
-\docparam{columnLength}{New size of the column. Valid only for DB_DATA_TYPE_VARCHAR
+\docparam{dataType}{Any one of DB\_DATA\_TYPE\_VARCHAR, DB\_DATA\_TYPE\_INTEGER,
+DB\_DATA\_TYPE\_FLOAT, DB\_DATA\_TYPE\_DATE.}
+\docparam{columnLength}{New size of the column. Valid only for DB\_DATA\_TYPE\_VARCHAR
dataType fields. Default is 0.}
\docparam{optionalParam}{Default is "".}
\wxheading{Remarks}
Cannot be used to modify the precision of a numeric column, therefore 'columnLength'
-is ignored unless the dataType is DB_DATA_TYPE_VARCHAR.
+is ignored unless the dataType is DB\_DATA\_TYPE\_VARCHAR.
Some datasources do not allow certain properties of a column to be changed if any rows
currently have data stored in that column. Those datasources that do allow columns
\membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
-\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxString &}{filename = SQL_LOG_FILENAME}, \param{bool }{ append = FALSE}}
+\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxString &}{filename = SQL\_LOG\_FILENAME}, \param{bool }{ append = FALSE}}
\wxheading{Parameters}
\docparam{state}{Either sqlLogOFF or sqlLogON (see \helpref{enum wxDbSqlLogState}{wxdbcolfor}). Turns logging of SQL commands sent to the datasource OFF or ON.}
-\docparam{filename}{{\it OPTIONAL}. Name of the file to which the log text is to be written. Default is SQL_LOG_FILENAME.}
+\docparam{filename}{{\it OPTIONAL}. Name of the file to which the log text is to be written. Default is SQL\_LOG\_FILENAME.}
\docparam{append}{{\it OPTIONAL}. Whether the file is appended to or overwritten. Default is FALSE.}
\wxheading{Remarks}
When called with {\it sqlLogOFF}, the logging file is closed, and any calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} are ignored.
+\membersection{wxDb::SQLColumnName}\label{wxdbsqlcolumnname}
+
+\func{const wxString}{SQLColumnName}{\param{const char *}{ colName}}
+
+Returns the column name in a form ready for use in SQL statements.
+In most cases, the column name is returned verbatim. But some databases
+(e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which
+must be specially quoted. For example, if the datasource allows spaces
+in the column name, the returned string will have the correct enclosing
+marks around the name to allow it to be properly included in a SQL statement
+for the DBMS that is currently connected to with this connection.
+
+\wxheading{Parameters}
+
+\docparam{colName}{Native name of the column in the table that is to be
+evaluated to determine if any special quoting marks needed to be added to it
+before including the column name in a SQL statement}
+
+\wxheading{See also}
+
+\helpref{wxDb::SQLTableName}{wxdbsqltablename}
+
+
+\membersection{wxDb::SQLTableName}\label{wxdbsqltablename}
+
+\func{const wxString}{SQLTableName}{\param{const char *}{ tableName}}
+
+Returns the table name in a form ready for use in SQL statements.
+In most cases, the table name is returned verbatim. But some databases
+(e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which
+must be specially quoted. For example, if the datasource allows spaces
+in the table name, the returned string will have the correct enclosing
+marks around the name to allow it to be properly included in a SQL statement
+for the data source that is currently connected to with this connection.
+
+\wxheading{Parameters}
+
+\docparam{tableName}{Native name of the table that is to be evaluated to
+determine if any special quoting marks needed to be added to it
+before including the table name in a SQL statement}
+
+\wxheading{See also}
+
+\helpref{wxDb::SQLColumnName}{wxdbsqlcolumnname}
+
+
\membersection{wxDb::TableExists}\label{wxdbtableexists}
\func{bool}{TableExists}{\param{const wxString &}{tableName}, \param{const wxChar *}{userID=NULL}, \param{const wxString &}{path=""}}
\wxheading{Return value}
-Returns the internal class DB_ERR code. See \helpref{wxDb::DB_STATUS}{wxdb} definition.
+Returns the internal class DB\_ERR code. See \helpref{wxDb::DB\_STATUS}{wxdb} definition.
\membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
\begin{verbatim}
void *PtrDataObj;
int SzDataObj;
- int SqlCtype;
+ SWORD SqlCtype;
\end{verbatim}
wxChar 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
+ SWORD SqlCtype; - C data type; e.g. SQL_C_LONG
void *PtrDataObj; - Address of the data object
int SzDataObj; - Size, in bytes, of the data object
bool KeyField; - Is column part of the PRIMARY KEY for the
the constructor automatically.
+\section{\class{wxDbColFor}}\label{wxdbcolfor}
+
+Beginning support for handling international formatting specifically on dates
+and floats.
+
+\begin{verbatim}
+ wxString s_Field; // Formated String for Output
+ wxString s_Format[7]; // Formated Objects - TIMESTAMP has
+ the biggest (7)
+ wxString s_Amount[7]; // Formated Objects - amount of
+ things that can be formatted
+ int i_Amount[7]; // Formated Objects -
+ TT MM YYYY HH MM SS m
+ int i_Nation; // 0 = timestamp
+ 1 = EU
+ 2 = UK
+ 3 = International
+ 4 = US
+ int i_dbDataType; // conversion of the 'sqlDataType'
+ to the generic data type used by
+ these classes
+ SWORD i_sqlDataType;
+\end{verbatim}
+
+The constructor for this class initializes all the values to zero or NULL.
+
+The destructor does nothing at this time.
+
+Only one function is provided with this class currently:
+
+
+\membersection{wxDbColFor::Format}\label{wxdbcolforformat}
+
+\func{int }{Format}{\param{int }{Nation}, \param{int }{dbDataType},
+\param{SWORD }{sqlDataType}, \param{short }{columnSize},
+\param{short }{decimalDigits}}\label{wxdbcolforformat}
+
+Work in progress, and should be inter-related with wxLocale eventually.
+
+
+\membersection{wxDbColFor::Initialize}\label{wxdbcolforinitialize}
+
+Simply initializes all member variables to a cleared state. Called by
+the constructor automatically.
+
+
\section{\class{wxDbColInf}}\label{wxdbcolinf}
Used with the \helpref{wxDb::GetColumns}{wxdbgetcolumns} functions for obtaining all retrievable information about a column's definition.
-\section{\class{wxDbColFor}}\label{wxdbcolfor}
-
-Beginning support for handling international formatting specifically on dates
-and floats.
-
-\begin{verbatim}
- wxString s_Field; // Formated String for Output
- wxString s_Format[7]; // Formated Objects - TIMESTAMP has
- the biggest (7)
- wxString s_Amount[7]; // Formated Objects - amount of
- things that can be formatted
- int i_Amount[7]; // Formated Objects -
- TT MM YYYY HH MM SS m
- int i_Nation; // 0 = timestamp
- 1 = EU
- 2 = UK
- 3 = International
- 4 = US
- int i_dbDataType; // conversion of the 'sqlDataType'
- to the generic data type used by
- these classes
- SWORD i_sqlDataType;
-\end{verbatim}
-
-The constructor for this class initializes all the values to zero or NULL.
-
-The destructor does nothing at this time.
-
-Only one function is provided with this class currently:
-
-
-\membersection{wxDbColFor::Format}\label{wxdbcolforformat}
-
-\func{int }{Format}{\param{int }{Nation}, \param{int }{dbDataType},
-\param{SWORD }{sqlDataType}, \param{short }{columnSize},
-\param{short }{decimalDigits}}\label{wxdbcolforformat}
-
-Work in progress, and should be inter-related with wxLocale eventually.
-
-
-\membersection{wxDbColFor::Initialize}\label{wxdbcolforinitialize}
-
-Simply initializes all member variables to a cleared state. Called by
-the constructor automatically.
-
-
\section{\class{wxDbConnectInf}}\label{wxdbconnectinf}
This class is used for holding the data necessary for connecting to the ODBC
\membersection{wxDbTable::wxDbTable}\label{wxdbtableconstr}
\func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const wxString &}{tblName},
- \param{const int }{nCols}, \param{const wxString &}{qryTblName = ""},
- \param{bool }{qryOnly = !wxDB_QUERY_ONLY}, \param{const wxString &}{tblPath = ""}}
+ \param{const UWORD }{numColumns}, \param{const wxString &}{qryTblName = ""},
+ \param{bool }{qryOnly = !wxDB\_QUERY\_ONLY}, \param{const wxString &}{tblPath = ""}}
Default constructor.
\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
+\docparam{numColumns}{The number of columns in the table. (Do NOT include the ROWID
column in the count if using Oracle).}
\docparam{qryTblName}{{\it OPTIONAL}. The name of the table or view to base
your queries on. This argument allows you to specify a table/view other than
\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.}
+Default is !wxDB\_QUERY\_ONLY.}
\docparam{tblPath}{{\it OPTIONAL}. Some datasources (such as dBase)
require a path to where the table is stored on the system. Default is "".}
\docparam{pSqlStmt}{Pointer to buffer for the SQL statement retrieved. To be
sure you have adequate space allocated for the SQL statement, allocate
-DB_MAX_STATEMENT_LEN bytes.}
+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,
+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 "".}
\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.}
+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.}
+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}
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
+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 datasource supports ROW IDs (Oracle). The ROW ID
column is used for efficiency purposes when available.
\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.}
+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,
+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 "".}
\wxheading{Remarks}
\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.}
+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.}
+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},
that the ODBC class library builds. This can be used for debugging purposes
if you are having problems executing your own SQL statements.
-If using 'typeOfWhere' set to DB_WHERE_MATCHING, any bound columns currently
+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.
member function to determine if the datasource currently connected to supports
this behavior or not before trying to select using "FOR UPDATE".
-If the wxDbTable instance was created with the parameter wxDB_QUERY_ONLY, then
+If the wxDbTable instance was created with the parameter wxDB\_QUERY\_ONLY, then
this function will return FALSE. For all known databases which do not support
the FOR UPDATE clause, this function will return FALSE also.
\membersection{wxDbTable::ClearMemberVar}\label{wxdbtableclearmembervar}
-\func{void}{ClearMemberVar}{\param{int }{colNo}, \param{bool }{setToNull=FALSE}}
+\func{void}{ClearMemberVar}{\param{UWORD }{colNo}, \param{bool }{setToNull=FALSE}}
Same as \helpref{wxDbTable::ClearMemberVars}{wxdbtableclearmembervars} except
that this function clears only the specified column of its values, and
programmer if desired.
-\normalbox{DO NOT CLOSE THE wxDB_DEFAULT_CURSOR!}
+\normalbox{DO NOT CLOSE THE wxDB\_DEFAULT\_CURSOR!}
\membersection{wxDbTable::Count}\label{wxdbtablecount}
\membersection{wxDbTable::CreateIndex}\label{wxdbtablecreateindex}
\func{bool}{CreateIndex}{\param{const wxString &}{idxName}, \param{bool }{unique},
-\param{int }{noIdxCols}, \param{wxDbIdxDef *}{pIdxDefs},
+\param{UWORD }{noIdxCols}, \param{wxDbIdxDef *}{pIdxDefs},
\param{bool }{attemptDrop=TRUE}}
This member function allows you to create secondary (non primary) indexes on
The first parameter, index name, must be unique and should be given a
meaningful name. Common practice is to include the table name as a prefix
in the index name (e.g. For table PARTS, you might want to call your index
-PARTS_IDX1). This will allow you to easily view all
+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
after executing this function.
-\membersection{wxDbTable::DB_STATUS}\label{wxdbtabledbstatus}
+\membersection{wxDbTable::DB\_STATUS}\label{wxdbtabledbstatus}
-\func{bool}{DB_STATUS}{\void}
+\func{bool}{DB\_STATUS}{\void}
-Accessor function that returns the wxDb private member variable DB_STATUS for
+Accessor function that returns the wxDb private member variable DB\_STATUS for
the database connection used by this instance of wxDbTable.
indicating the reason. Even if the cursor could not be deleted, the HSTMT
that is passed in is deleted, and the pointer is set to NULL.
-\normalbox{DO NOT DELETE THE wxDB_DEFAULT_CURSOR!}
+\normalbox{DO NOT DELETE THE wxDB\_DEFAULT\_CURSOR!}
\membersection{wxDbTable::DeleteMatching}\label{wxdbtabledeletematching}
\membersection{wxDbTable::GetNumberOfColumns}\label{wxdbtablegetnumberofcolumns}
-\func{int }{GetNumberOfColumns}{}
+\func{UWORD }{GetNumberOfColumns}{}
Accessor function that returns the number of columns that are statically
bound for access by the wxDbTable instance.
wxStrcpy(parts->PartName, "10");
wxStrcpy(parts->PartDesc, "Part #10");
parts->Qty = 1000;
- RETCODE retcode = parts.Insert();
+ RETCODE retcode = parts->Insert();
switch(retcode)
{
case DB_SUCCESS:
\membersection{wxDbTable::IsColNull}\label{wxdbtableiscolnull}
-\func{bool }{IsColNull}{\param{int }{colNo}}
+\func{bool }{IsColNull}{\param{UWORD }{colNo}} const
Used primarily in the ODBC class library to determine if a column value is
set to "NULL". Works for all data types supported by the ODBC class library.
\membersection{wxDbTable::Open}\label{wxdbtableopen}
-\func{bool }{Open}{\param{bool }{checkPrivileges=FALSE}}
+\func{bool }{Open}{\param{bool }{checkPrivileges=FALSE}, \param{bool }{checkTableExists=TRUE}}
Every wxDbTable instance must be opened before it can be used. This function
checks for the existence of the requested table, binds columns, creates required
-cursors, (insert/select and update if connection is not wxDB_QUERY_ONLY) and
+cursors, (insert/select and update if connection is not wxDB\_QUERY\_ONLY) and
constructs the insert statement that is to be used for inserting data as a new
row in the datasource.
whether the current connected user has at least SELECT privileges to access the
table to which they are trying to open. Default is FALSE.}
+\docparam{checkTableExists}{Indicates whether the Open() function should check
+whether the table exists in the database or not before opening it. Default is TRUE.}
+
\wxheading{Remarks}
If the function returns a FALSE value due to the table not existing, a log
entry is recorded for the datasource connection indicating the problem
that was detected when checking for table existence. Note that it is usually
best for the calling routine to check for the existence of the table and for
-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
+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
explanation as to why a table cannot be opened.
Checking the user's privileges on a table can be quite time consuming during
alphabetized/numeric sorting sequence that the result set is to be returned
in. If a FROM clause has also been specified, each column name specified in
the ORDER BY clause should be prefaced with the table name to which the column
-belongs using DOT notation (TABLE_NAME.COLUMN_NAME).}
+belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
\wxheading{Return value}
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
+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.
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 {\bf last}
+ 3. The ROWID can be included in your SELECT statement as the {\bf 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
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
+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
+PartNumber variable that is bound to the PART\_NUMBER column in the wxDbTable
object to "32", and then call wxDbTable::QueryMatching().
\wxheading{Parameters}
\membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
-\func{void}{SetColDefs}{\param{int }{index}, \param{const wxString &}{fieldName},
-\param{int }{dataType}, \param{void *}{pData}, \param{int }{cType},
+\func{void}{SetColDefs}{\param{UWORD }{index}, \param{const wxString &}{fieldName},
+\param{int }{dataType}, \param{void *}{pData}, \param{SWORD }{cType},
\param{int }{size}, \param{bool }{keyField = FALSE}, \param{bool }{upd = TRUE},
\param{bool }{insAllow = TRUE}, \param{bool }{derivedCol = FALSE}}
-\func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{ULONG }{numCols}}
+\func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{UWORD }{numCols}}
\wxheading{Parameters}
\membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
-\func{bool}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB_DEFAULT_CURSOR}}
+\func{bool}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB\_DEFAULT\_CURSOR}}
\wxheading{Parameters}
\docparam{hstmtActivate}{{\it OPTIONAL}. Pointer to the cursor that is to
become the current cursor. Passing no cursor handle will reset the cursor
back to the wxDbTable's default (original) cursor that was created when the
-wxDbTable instance was first created. Default is wxDB_DEFAULT_CURSOR.}
+wxDbTable instance was first created. Default is wxDB\_DEFAULT\_CURSOR.}
\wxheading{Remarks}
\membersection{wxDbTable::SetColNull}\label{wxdbtablesetcolnull}
-\func{bool}{SetColNull}{\param{int }{colNo}, \param{bool }{set=TRUE}}
+\func{bool}{SetColNull}{\param{UWORD }{colNo}, \param{bool }{set=TRUE}}
\func{bool}{SetColNull}{\param{const wxString &}{colName},
\param{bool }{set=TRUE}}
alphabetized sorting sequence that the result set is to be returned in. If
a FROM clause has also been specified, each column name specified in the
ORDER BY clause should be prefaced with the table name to which the column
-belongs using DOT notation (TABLE_NAME.COLUMN_NAME).}
+belongs using DOT notation (TABLE\_NAME.COLUMN\_NAME).}
\wxheading{Remarks}
that is legal in standard where clauses. If a FROM clause has also been
specified, each column name specified in the ORDER BY clause should be
prefaced with the table name to which the column belongs using DOT notation
-(TABLE_NAME.COLUMN_NAME).}
+(TABLE\_NAME.COLUMN\_NAME).}
\wxheading{Remarks}
Eventually, accessor functions will be added for this class
-
\membersection{wxDbTableInf::Initialize}\label{wxdbtableinfinitialize}
Simply initializes all member variables to a cleared state. Called by
the constructor automatically.
+
projects / wxWidgets.git / blobdiff