AuroraMiddleware/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Did a small amount of proofreading of the ODBC docs.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@15397 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Julian Smart 2002-05-06 13:46:24 +00:00
parent 6e8e9b6628
commit 2564094bf4
2 changed files with 224 additions and 335 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
docs/latex/wx/db.tex
View File

@ -6,6 +6,9 @@ database connection allows function to be performed directly on the
datasource, as well as allowing access to any tables/views defined in
the datasource to which the user has sufficient privileges.
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\wxheading{Include files}
<wx/db.h>
@ -81,7 +84,6 @@ These are the databases currently tested and working with the ODBC classes. A c
See the remarks in \helpref{wxDb::Dbms}{wxdbdbms} for exceptions/issues with each of these database engines.
\wxheading{Public member variables}
\docparam{SWORD {\bf wxDb::cbErrorMsg}}{This member variable is populated as a result of calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}. Contains the count of bytes in the wxDb::errorMsg string.}
@ -267,7 +269,6 @@ both types of cursors.
The following functions are used in conjunction with the wxDb class.
\func{void}{wxDbCloseConnections}{\void}
\wxheading{Remarks}
@ -356,14 +357,12 @@ cached connections created by calls to wxDbGetConnection().
Writes a message to the wxLog window (stdout usually) when an internal
error situation occurs. This function only works in DEBUG builds
\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}}
\wxheading{Remarks}
@ -372,11 +371,12 @@ This routine queries the ODBC driver manager for a list of available
datasources. Repeatedly call this function to obtain all the datasources
available through the ODBC driver manager on the current workstation.
\begin{verbatim}
wxStringList strList;
while (wxDbGetDataSource(DbConnectInf.GetHenv(), Dsn, SQL\_MAX\_DSN\_LENGTH+1, DsDesc, 255))
strList.Add(Dsn);
\end{verbatim}
\latexignore{\rtfignore{\wxheading{Members}}}
@ -419,8 +419,7 @@ be created and opened before any database activity can occur.
\wxheading{See also}
\helpref{wxDbGetConnection}{wxdbfunctions},
\helpref{wxDbGetConnection}{wxdbfunctions}
\membersection{wxDb::Catalog}\label{wxdbcatalog}
@ -652,7 +651,6 @@ perform an action (see the example below).
return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
\end{verbatim}
\membersection{wxDb::DispNextError}\label{wxdbdispnexterror}
\func{void}{DispNextError}{\void}
@ -710,7 +708,6 @@ If the view does not exist, this function will return TRUE. Note that views are
\membersection{wxDb::ExecSql}\label{wxdbexecsql}
\func{bool}{ExecSql}{\param{const wxString \&}{pSqlStmt}}
Allows a native SQL command to be executed directly against the datasource. In addition to being able to run any standard SQL command, use of this function allows a user to (potentially) utilize features specific to the datasource they are connected to that may not be available through ODBC. The ODBC driver will pass the specified command directly to the datasource.
@ -730,7 +727,6 @@ of processing.
\helpref{wxDb::GetData}{wxdbgetdata}, \helpref{wxDb::GetNext}{wxdbgetnext}
\membersection{wxDb::FwdOnlyCursors}\label{wxdbfwdonlycursors}
\func{bool}{IsFwdOnlyCursors}{\void}
@ -843,7 +839,6 @@ to avoid undesired unbinding of columns.}
}
\end{verbatim}
\membersection{wxDb::GetData}\label{wxdbgetdata}
\func{bool}{GetData}{\param{UWORD}{ colNo}, \param{SWORD}{ cType},
@ -1069,7 +1064,6 @@ function to be able to successfully grant the indicated privileges.
db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
\end{verbatim}
\membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}
\func{bool}{IsFwdOnlyCursors}{\void}
@ -1112,7 +1106,6 @@ versions prior to 2.4.
\helpref{wxDb constructor}{wxdbconstr}, \helpref{wxDbGetConnection}{wxdbfunctions}
\membersection{wxDb::IsOpen}\label{wxdbisopen}
\func{bool}{IsOpen}{\void}
@ -1133,7 +1126,6 @@ only way to know if complete initialization of this wxDb connection was
successful or not. See \helpref{wxDb::Open}{wxdbopen} for more details on
partial failures to open a connection instance.
\membersection{wxDb::LogError}\label{wxdblogerror}
\func{void}{LogError}{\param{const wxString \&}{errMsg} \param{const wxString \&}{SQLState=""}}
@ -1154,7 +1146,6 @@ text into the SQL log file.
\helpref{wxDb::WriteSqlLog}{wxdbwritesqllog}
\membersection{wxDb::ModifyColumn}\label{wxdbmodifycolumn}
\func{void}{ModifyColumn}{\param{const wxString \&}{tableName} \param{const wxString \&}{ColumnName}
@ -1283,7 +1274,6 @@ must maintain the memory for these three strings for the life of the wxDb instan
}
\end{verbatim}
\membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}
\func{bool}{RollbackTrans}{\void}
@ -1306,7 +1296,6 @@ use this connection.}
\helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors
\membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
\func{void}{SetDebugErrorMessages}{\param{bool }{state}}
@ -1327,7 +1316,6 @@ When compiled in release mode (FINAL=1), this setting has no affect.
\helpref{wxDb constructor}{wxdbconstr}
\membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxString \&}{filename = SQL\_LOG\_FILENAME}, \param{bool }{ append = FALSE}}
@ -1344,7 +1332,6 @@ When called with {\it sqlLogON}, all commands sent to the datasource engine are
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}}
@ -1367,7 +1354,6 @@ before including the column name in a SQL statement}
\helpref{wxDb::SQLTableName}{wxdbsqltablename}
\membersection{wxDb::SQLTableName}\label{wxdbsqltablename}
\func{const wxString}{SQLTableName}{\param{const char *}{ tableName}}
@ -1390,7 +1376,6 @@ before including the table name in a SQL statement}
\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=""}}
@ -1422,7 +1407,6 @@ This function does not indicate whether or not the user has privileges to query
\helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
\membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}
\func{bool}{TablePrivileges}{\param{const wxString \&}{tableName}, \param{const wxString \&}{priv},
@ -1510,7 +1494,6 @@ Converts an ODBC sqlstate to an internal error code.
Returns the internal class DB\_ERR code. See \helpref{wxDb::DB\_STATUS}{wxdb} definition.
\membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
\func{bool}{WriteSqlLog}{\param{const wxString \&}{logMsg}}
@ -1536,19 +1519,20 @@ FALSE without performing the requested log, otherwise TRUE is returned.
\helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
\section{\class{wxDbColDataPtr}}\label{wxdbcoldataptr}
Pointer to dynamic column definitions for use with a wxDbTable instance.
Currently there are no member functions for this class.
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\begin{verbatim}
void *PtrDataObj;
int SzDataObj;
SWORD SqlCtype;
\end{verbatim}
\section{\class{wxDbColDef}}\label{wxdbcoldef}
This class is used to hold information about the columns bound to an
@ -1591,15 +1575,14 @@ public.
\wxheading{See also}
\helpref{database classes overview}{odbcoverview},
\helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs}, \helpref{wxDb constructor}{wxdbconstr}
\membersection{wxDbColDef::Initialize}\label{wxdbcoldefinitialize}
Simply initializes all member variables to a cleared state. Called by
the constructor automatically.
\section{\class{wxDbColFor}}\label{wxdbcolfor}
Beginning support for handling international formatting specifically on dates
@ -1628,8 +1611,10 @@ 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:
Only one function is provided with this class currently.
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\membersection{wxDbColFor::Format}\label{wxdbcolforformat}
@ -1639,13 +1624,11 @@ Only one function is provided with this class currently:
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.
@ -1686,14 +1669,14 @@ The constructor for this class initializes all the values to zero, "", or NULL.
The destructor for this class takes care of deleting the pColFor member if
it is non-NULL.
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\membersection{wxDbColInf::Initialize}\label{wxdbcolinfinitialize}
Simply initializes all member variables to a cleared state. Called by
the constructor automatically.
\section{\class{wxDbConnectInf}}\label{wxdbconnectinf}
This class is used for holding the data necessary for connecting to the ODBC
@ -1702,6 +1685,8 @@ name, user ID, password and default directory path (used with dBase). Other
optional fields held in this class are and file type, both for future
functions planned to be added for creating/manipulating datasource definitions.
\membersection{wxDbConnectInf::wxDbConnectInfo}
\func{}{wxDbConnectInf}{\void}
Default constructor.
@ -1713,7 +1698,7 @@ Default constructor.
Constructor which allows initial settings of all the classes member variables.
See the special not below on the henv parameter for forcing this constructor
See the special note below on the henv parameter for forcing this constructor
to create a SQL environment handle automatically, rather than needing to pass
one in to the function.
@ -1765,7 +1750,6 @@ automatically, and manage the destruction of the handle.
\helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv},
\helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv}
\membersection{wxDbConnectInf::\destruct{wxDbConnectInf}}\label{wxdbconnectinfdestr}
\func{}{\destruct{wxDbConnectInf}}{}
@ -1776,7 +1760,6 @@ also takes care of calling
\helpref{wxDConnectInf::FreeHenv}{wxdbconnectinffreehenv} to free the
SQL environment handle.
\membersection{wxDbConnectInf::AllocHenv}\label{wxdbconnectinfallochenv}
\func{bool }{AllocHenv}{\void}
@ -1789,7 +1772,6 @@ an ODBC datasource.
This function can be automatically called by the long from of the
\helpref{wxDbConnectInf}{wxdbconnectinf} constructor.
\membersection{wxDbConnectInf::FreeHenv}\label{wxdbconnectinffreehenv}
\func{void}{FreeHenv}{\void}
@ -1805,13 +1787,11 @@ is reset to be FALSE, so that any future handles created using the
\helpref{wxDbConnectInf::AllocHenv}{wxdbconnectinfallochenv} function
must be manually released with a call to this function.
\membersection{wxDbConnectInf::Initialize}\label{wxdbconnectinfinitialize}
Simply initializes all member variables to a cleared state. Called by
the constructor automatically.
\membersection{wxDbConnectInf::GetAuthStr}\label{wxdbconnectinfgetauthstr}
\func{const wxChar *}{GetAuthStr}{\void}
@ -1821,7 +1801,6 @@ instance that will be used with the user ID.
Synonymous with \helpref{wxDbConnectInf::GetPassword}{wxdbconnectinfgetpassword}
\membersection{wxDbConnectInf::GetDefaultDir}\label{wxdbconnectinfgetdefaultdir}
\func{const wxChar *}{GetDefaultDir}{\void}
@ -1831,7 +1810,6 @@ table is stored. This directory is only used for file based datasources like
dBase. MS-Access does not require this to be set, as the path is set in the
ODBC Administrator for MS-Access.
\membersection{wxDbConnectInf::GetDescription}\label{wxdbconnectinfgetdescription}
\func{const wxChar *}{GetDescription}{\void}
@ -1841,7 +1819,6 @@ instance.
NOTE: Description is a FUTURE USE item and is unused currently.
\membersection{wxDbConnectInf::GetDsn}\label{wxdbconnectinfgetdsn}
\func{const wxChar *}{GetDsn}{\void}
@ -1849,7 +1826,6 @@ NOTE: Description is a FUTURE USE item and is unused currently.
Accessor function to return the datasource name assigned for this class
instance.
\membersection{wxDbConnectInf::GetFileType}\label{wxdbconnectinfgetfiletype}
\func{const wxChar *}{GetFileType}{\void}
@ -1859,7 +1835,6 @@ this class instance.
NOTE: FileType is a FUTURE USE item and is unused currently.
\membersection{wxDbConnectInf::GetHenv}\label{wxdbconnectinfgethenv}
\func{const HENV}{GetHenv}{\void}
@ -1867,7 +1842,6 @@ NOTE: FileType is a FUTURE USE item and is unused currently.
Accessor function to return the SQL environment handle being managed
by this class instance.
\membersection{wxDbConnectInf::GetPassword}\label{wxdbconnectinfgetpassword}
\func{const wxChar *}{GetPassword}{\void}
@ -1877,7 +1851,6 @@ instance that will be used with the user ID.
Synonymous with \helpref{wxDbConnectInf::GetAuthStr}{wxdbconnectinfgetauthstr}
\membersection{wxDbConnectInf::GetUid}\label{wxdbconnectinfgetuid}
\func{const wxChar *}{GetUid}{\void}
@ -1885,7 +1858,6 @@ Synonymous with \helpref{wxDbConnectInf::GetAuthStr}{wxdbconnectinfgetauthstr}
Accessor function to return the user ID assigned for this class
instance.
\membersection{wxDbConnectInf::GetUserID}\label{wxdbconnectinfgetuserid}
\func{const wxChar *}{GetUserID}{\void}
@ -1893,7 +1865,6 @@ instance.
Accessor function to return the user ID assigned for this class
instance.
\membersection{wxDbConnectInf::SetAuthStr}\label{wxdbconnectinfsetauthstr}
\func{\void}{SetAuthStr}{const wxString \&authstr}
@ -1903,7 +1874,6 @@ instance that will be used with the user ID.
Synonymous with \helpref{wxDbConnectInf::SetPassword}{wxdbconnectinfsetpassword}
\membersection{wxDbConnectInf::SetDefaultDir}\label{wxdbconnectinfsetdefaultdir}
\func{\void}{SetDefaultDir}{const wxString \&defDir}
@ -1913,7 +1883,6 @@ table is stored. This directory is only used for file based datasources like
dBase. MS-Access does not require this to be set, as the path is set in the
ODBC Administrator for MS-Access.
\membersection{wxDbConnectInf::SetDescription}\label{wxdbconnectinfsetdescription}
\func{\void}{SetDescription}{const wxString \&desc}
@ -1923,14 +1892,12 @@ instance.
NOTE: Description is a FUTURE USE item and is unused currently.
\membersection{wxDbConnectInf::SetDsn}\label{wxdbconnectinfsetdsn}
\func{\void}{SetDsn}{const wxString \&dsn}
Accessor function to assign the datasource name for this class instance.
\membersection{wxDbConnectInf::SetFileType}\label{wxdbconnectinfsetfiletype}
\func{\void}{SetFileType}{const wxString \&}
@ -1940,14 +1907,12 @@ this class instance.
NOTE: FileType is a FUTURE USE item and is unused currently.
\membersection{wxDbConnectInf::SetHenv}\label{wxdbconnectinfsethenv}
\func{void}{SetHenv}{\param{const HENV }{henv}}
Accessor function to set the SQL environment handle for this class instance.
\membersection{wxDbConnectInf::SetPassword}\label{wxdbconnectinfsetpassword}
\func{\void}{SetPassword}{const wxString \&password}
@ -1957,22 +1922,18 @@ instance that will be used with the user ID.
Synonymous with \helpref{wxDbConnectInf::SetAuthStr}{wxdbconnectinfsetauthstr}
\membersection{wxDbConnectInf::SetUid}\label{wxdbconnectinfsetuid}
\func{\void}{SetUid}{const wxString \&uid}
Accessor function to set the user ID for this class instance.
\membersection{wxDbConnectInf::SetUserID}\label{wxdbconnectinfsetuserid}
\func{\void}{SetUserID}{const wxString \&userID}
Accessor function to assign the user ID for this class instance.
\section{\class{wxDbIdxDef}}\label{wxdbidxdef}
Used in creation of non-primary indexes. Currently there are no member
@ -1987,6 +1948,8 @@ functions for this class.
There are no constructors/destructors as of this time, and no member functions.
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\section{\class{wxDbInf}}\label{wxdbinf}
@ -2012,17 +1975,22 @@ The constructor for this class initializes all the values to zero, "", or NULL.
The destructor for this class takes care of deleting the pTableInf member if
it is non-NULL.
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\membersection{wxDbInf::Initialize}\label{wxdbinfinitialize}
Simply initializes all member variables to a cleared state. Called by
the constructor automatically.
\section{\class{wxDbTable}}\label{wxdbtable}
A wxDbTable instance provides re-usable access to rows of data in
a table contained within the associated ODBC datasource
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\wxheading{Include files}
<wx/dbtable.h>\\
@ -2103,7 +2071,6 @@ require a path to where the table is stored on the system. Default is "".}
Virtual default destructor.
\membersection{wxDbTable::BuildDeleteStmt}\label{wxdbtablebuilddeletestmt}
\func{void}{BuildDeleteStmt}{\param{wxString \&}{pSqlStmt},
@ -2132,7 +2099,6 @@ WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbt
and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
this function.
\membersection{wxDbTable::BuildSelectStmt}\label{wxdbtablebuildselectstmt}
\func{void}{BuildSelectStmt}{\param{wxString \&}{pSqlStmt},
@ -2167,7 +2133,6 @@ WHERE and FROM clauses specified using
and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
this function.
\membersection{wxDbTable::BuildUpdateStmt}\label{wxdbtablebuildupdatestmt}
\func{void}{BuildUpdateStmt}{\param{wxString \&}{pSqlStmt}, \param{int }{typeOfUpd},
@ -2207,7 +2172,6 @@ WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbt
and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
this function.
\membersection{wxDbTable::BuildWhereStmt}\label{wxdbtablebuildwherestmt}
\func{void}{BuildSelectStmt}{\param{wxString \&}{pWhereClause},
@ -2243,7 +2207,6 @@ 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}
@ -2264,7 +2227,6 @@ If the wxDbTable instance was created with the parameter wxDB\_QUERY\_ONLY, then
this function will return FALSE. For all known databases which do not support
the FOR UPDATE clause, this function will return FALSE also.
\membersection{wxDbTable::CanUpdateByROWID}\label{wxdbtablecanupdatebyrowid}
\func{bool}{CanUpdateByROWID}{\void}
@ -2325,7 +2287,6 @@ flagged as being a NULL value stored in the bound memory variable. If TRUE,
then any value stored in the bound member variable is cleared. Default is
FALSE.}
\membersection{wxDbTable::ClearMemberVars}\label{wxdbtableclearmembervars}
\func{void}{ClearMemberVars}{\param{bool }{setToNull=FALSE}}
@ -2353,7 +2314,6 @@ functions build their WHERE clauses from non-zero columns. To call either
3) Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
\end{verbatim}
\membersection{wxDbTable::CloseCursor}\label{wxdbtableclosecursor}
\func{bool}{CloseCursor}{\param{HSTMT}{cursor}}
@ -2369,10 +2329,8 @@ Closes the specified cursor associated with the wxDbTable object.
Typically handled internally by the ODBC class library, but may be used by the
programmer if desired.
\normalbox{DO NOT CLOSE THE wxDB\_DEFAULT\_CURSOR!}
\membersection{wxDbTable::Count}\label{wxdbtablecount}
\func{ULONG }{Count}{\param{const wxString \&}{args="*"}}
@ -2427,7 +2385,6 @@ this function.
totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
\end{verbatim}
\membersection{wxDbTable::CreateIndex}\label{wxdbtablecreateindex}
\func{bool}{CreateIndex}{\param{const wxString \&}{idxName}, \param{bool }{unique},
@ -2513,7 +2470,6 @@ after executing this function.
parts->CreateIndex(indexName, TRUE, 2, idxDef);
\end{verbatim}
\membersection{wxDbTable::CreateTable}\label{wxdbtablecreatetable}
\func{bool}{CreateTable}{\param{bool }{attemptDrop=TRUE}}
@ -2545,7 +2501,6 @@ information on describing the columns of the table.
It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
after executing this function.
\membersection{wxDbTable::DB\_STATUS}\label{wxdbtabledbstatus}
\func{bool}{DB\_STATUS}{\void}
@ -2553,7 +2508,6 @@ after executing this function.
Accessor function that returns the wxDb private member variable DB\_STATUS for
the database connection used by this instance of wxDbTable.
\membersection{wxDbTable::Delete}\label{wxdbtabledelete}
\func{bool}{Delete}{\void}
@ -2582,7 +2536,6 @@ 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}}
@ -2605,7 +2558,6 @@ that is passed in is deleted, and the pointer is set to NULL.
\normalbox{DO NOT DELETE THE wxDB\_DEFAULT\_CURSOR!}
\membersection{wxDbTable::DeleteMatching}\label{wxdbtabledeletematching}
\func{bool}{DeleteMatching}{\void}
@ -2647,7 +2599,6 @@ 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}
@ -2731,7 +2682,6 @@ 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}
@ -2752,7 +2702,6 @@ database to determine the behavior.
It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
after executing this function.
\membersection{wxDbTable::From}\label{wxdbtablefrom}
\func{const wxString \&}{From}{}
@ -2805,7 +2754,6 @@ To determine the number of elements pointed to by the returned
These column definitions must not be manually redefined after they have been
set.
\membersection{wxDbTable::GetCursor}\label{wxdbtablegetcursor}
\func{HSTMT}{GetCursor}{\void}
@ -2822,7 +2770,6 @@ cursor can be set back to being the cursor in use.
\helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}, \helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor}
\membersection{wxDbTable::GetDb}\label{wxdbtablegetdb}
\func{wxDb *}{GetDb}{}
@ -2830,7 +2777,6 @@ cursor can be set back to being the cursor in use.
Accessor function for the private member variable pDb which is a pointer to
the datasource connection that this wxDbTable instance uses.
\membersection{wxDbTable::GetFirst}\label{wxdbtablegetfirst}
\func{bool}{GetFirst}{\void}
@ -2853,7 +2799,6 @@ return FALSE, and the data contained in the bound columns will be undefined.
\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
\membersection{wxDbTable::GetFromClause}\label{wxdbtablegetfromclause}
\func{const wxString \&}{GetFromClause}{}
@ -2865,7 +2810,6 @@ Accessor function that returns the current FROM setting assigned with the
\helpref{wxDbTable::From}{wxdbtablefrom}
\membersection{wxDbTable::GetLast}\label{wxdbtablegetlast}
\func{bool}{GetLast}{\void}
@ -2888,7 +2832,6 @@ return FALSE, and the data contained in the bound columns will be undefined.
\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
\membersection{wxDbTable::GetNewCursor}\label{wxdbtablegetnewcursor}
\func{HSTMT *}{GetNewCursor}{\param{bool }{setCursor=FALSE},
@ -2913,7 +2856,6 @@ This new cursor must be closed using
by the calling program before the wxDbTable instance is deleted, or both
memory and resource leaks will occur.
\membersection{wxDbTable::GetNext}\label{wxdbtablegetnext}
\func{bool}{GetNext}{\void}
@ -2938,7 +2880,6 @@ This function works with both forward and backward scrolling cursors.
\wxheading{See also}
\helpref{wxDbTable::++}{wxdbtableplusplus}
\membersection{wxDbTable::GetNumberOfColumns}\label{wxdbtablegetnumberofcolumns}
\func{UWORD }{GetNumberOfColumns}{}
@ -2946,7 +2887,6 @@ This function works with both forward and backward scrolling cursors.
Accessor function that returns the number of columns that are statically
bound for access by the wxDbTable instance.
\membersection{wxDbTable::GetOrderByClause}\label{wxdbtablegetorderbyclause}
\func{const wxString \&}{GetOrderByClause}{}
@ -2958,7 +2898,6 @@ the \helpref{wxDbTable::SetOrderByClause}{wxdbtablesetorderbyclause}.
\helpref{wxDbTable::OrderBy}{wxdbtableorderby}
\membersection{wxDbTable::GetPrev}\label{wxdbtablegetprev}
\func{bool}{GetPrev}{\void}
@ -2988,7 +2927,6 @@ return FALSE, and the data contained in the bound columns will be undefined.
\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors},
\helpref{wxDbTable::--}{wxdbtableminusminus}
\membersection{wxDbTable::GetQueryTableName}\label{wxdbtablegetquerytablename}
\func{const wxString \&}{GetQueryTableName}{}
@ -3001,7 +2939,6 @@ created.
\helpref{wxDbTable constructor}{wxdbtableconstr}
\membersection{wxDbTable::GetRowNum}\label{wxdbtablegetrownum}
\func{UWORD}{GetRowNum}{\void}
@ -3017,7 +2954,6 @@ Row number with some datasources/ODBC drivers is the position in the result set,
while in others it may be a physical position in the database. Check your
database documentation to find out which behavior is supported.
\membersection{wxDbTable::GetTableName}\label{wxdbtablegettablename}
\func{const wxString \&}{GetTableName}{}
@ -3025,7 +2961,6 @@ database documentation to find out which behavior is supported.
Accessor function that returns the name of the table that was indicated
as being the table that this wxDbTable instance was associated with.
\membersection{wxDbTable::GetTablePath}\label{wxdbtablegettablepath}
\func{const wxString \&}{GetTablePath}{}
@ -3037,7 +2972,6 @@ during creation of this wxDbTable instance.
Currently only applicable to dBase and MS-Access datasources.
\membersection{wxDbTable::GetWhereClause}\label{wxdbtablegetwhereclause}
\func{const wxString \&}{GetWhereClause}{}
@ -3049,7 +2983,6 @@ Accessor function that returns the current WHERE setting assigned with the
\helpref{wxDbTable::Where}{wxdbtablewhere}
\membersection{wxDbTable::Insert}\label{wxdbtableinsert}
\func{int }{Insert}{\void}
@ -3102,7 +3035,6 @@ this function to commit or rollback the insertion.
}
\end{verbatim}
\membersection{wxDbTable::IsColNull}\label{wxdbtableiscolnull}
\func{bool }{IsColNull}{\param{UWORD }{colNo}} const
@ -3118,8 +3050,7 @@ calls which defined the columns accessible to this wxDbTable instance.}
\wxheading{Remarks}
NULL column support is currently not fully implemented as of wxWindows 2.4
NULL column support is currently not fully implemented as of wxWindows 2.4.
\membersection{wxDbTable::IsCursorClosedOnCommit}\label{wxdbtableiscursorclosedoncommit}
@ -3141,7 +3072,6 @@ If more than one wxDbTable instance used the same database connection, all curso
which use the database connection are closed on the commit if this function
indicates TRUE.
\membersection{wxDbTable::IsQueryOnly}\label{wxdbtableisqueryonly}
\func{bool }{IsQueryOnly}{}
@ -3151,7 +3081,6 @@ was created to allow only queries to be performed on the bound columns. If
this function returns TRUE, then no actions may be performed using this
wxDbTable instance that would modify (insert/delete/update) the table's data.
\membersection{wxDbTable::Open}\label{wxdbtableopen}
\func{bool }{Open}{\param{bool }{checkPrivileges=FALSE}, \param{bool }{checkTableExists=TRUE}}
@ -3196,7 +3125,6 @@ function can significantly speed up the privileges checks.
\helpref{wxDb::TableExists}{wxdbtableexists},
\helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
\membersection{wxDbTable::OrderBy}\label{wxdbtableorderby}
\func{const wxString \&}{OrderBy}{}
@ -3230,7 +3158,6 @@ The second form of the function has no return value.
\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}}
@ -3316,7 +3243,6 @@ clauses.}
dispPart(parts); // user defined function
\end{verbatim}
\membersection{wxDbTable::QueryBySqlStmt}\label{wxdbtablequerybysqlstmt}
\func{bool}{QueryBySqlStmt}{\param{const wxString \&}{pSqlStmt}}
@ -3417,7 +3343,6 @@ either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
where device_id = 12)
\end{verbatim}
\membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
\func{virtual bool }{QueryMatching}{\param{bool }{forUpdate=FALSE},
@ -3482,7 +3407,6 @@ this function.
dispPart(parts); // Some application defined function
\end{verbatim}
\membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
\func{bool }{QueryOnKeyFields}{\param{bool }{forUpdate=FALSE},
@ -3532,7 +3456,6 @@ this function.
dispPart(parts); // Some application defined function
\end{verbatim}
\membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
\func{bool}{Refresh}{\void}
@ -3555,7 +3478,6 @@ 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{UWORD }{index}, \param{const wxString \&}{fieldName},
@ -3652,7 +3574,6 @@ were to be copied over to another datasource or table.
SQL_C_CHAR, PART_NUMBER_LEN, TRUE, FALSE,TRUE,FALSE);
\end{verbatim}
\membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
\func{bool}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB\_DEFAULT\_CURSOR}}
@ -3682,7 +3603,6 @@ and saving a pointer to that cursor.
\helpref{wxDbTable::GetCursor}{wxdbtablegetcursor},
\helpref{wxDbTable::SetCursor}{wxdbtablesetcursor}
\membersection{wxDbTable::SetFromClause}\label{wxdbtablesetfromclause}
\func{void}{SetFromClause}{\param{const wxString \&}{From}}
@ -3732,7 +3652,6 @@ the datasource knows on which column values the tables should be joined on.
\helpref{wxDbTable::From}{wxdbtablefrom},
\helpref{wxDbTable::GetFromClause}{wxdbtablegetfromclause}
\membersection{wxDbTable::SetColNull}\label{wxdbtablesetcolnull}
\func{bool}{SetColNull}{\param{UWORD }{colNo}, \param{bool }{set=TRUE}}
@ -3756,14 +3675,12 @@ this wxDbTable object.}
the column to NULL, passing FALSE sets the column to be non-NULL. Default is
TRUE.}
\wxheading{Remarks}
No database updates are done by this function. It only operates on the
member variables in memory. Use and insert or update function to store this
value to disk.
\membersection{wxDbTable::SetOrderByClause}\label{wxdbtablesetorderbyclause}
\func{void}{SetOrderByClause}{\param{const wxString \&}{OrderBy}}
@ -3803,7 +3720,6 @@ Do {\bf not} include the keywords "ORDER BY" when setting the ORDER BY clause.
\helpref{wxDbTable::OrderBy}{wxdbtableorderby},
\helpref{wxDbTable::GetOrderByClause}{wxdbtablegetorderbyclause}
\membersection{wxDbTable::SetQueryTimeout}\label{wxdbtablesetquerytimeout}
\func{bool}{SetQueryTimeout}{\param{UDWORD }{nSeconds}}
@ -3821,7 +3737,6 @@ 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}}
@ -3872,7 +3787,6 @@ Do {\bf not} include the keywords "WHERE" when setting the WHERE clause.
\helpref{wxDbTable::Where}{wxdbtablewhere},
\helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause}
\membersection{wxDbTable::Update}\label{wxdbtableupdate}
\func{bool }{Update}{\void}
@ -3912,7 +3826,6 @@ this function to commit or rollback the update.
sqlStmt = "update PART set QTY = 0 where PART_NUMBER = '32'";
\end{verbatim}
\membersection{wxDbTable::UpdateWhere}\label{wxdbtableupdatewhere}
\func{bool}{UpdateWhere}{\param{const wxString \&}{pWhereClause}}
@ -3938,7 +3851,6 @@ A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
this function to commit or rollback the update(s).
\membersection{wxDbTable::Where}\label{wxdbtablewhere}
\func{const wxString \&}{Where}{}
@ -3968,8 +3880,6 @@ the where clause successfully.
\helpref{wxDbTable::GetWhereClause}{wxdbtablegetwhereclause},
\helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
\membersection{wxDbTable::operator $++$}\label{wxdbtableplusplus}
\func{bool}{operator $++$}{\void}
@ -3980,7 +3890,6 @@ Synonym for \helpref{wxDbTable::GetNext}{wxdbtablegetnext}
\helpref{wxDbTable::GetNext}{wxdbtablegetnext}
\membersection{wxDbTable::operator $--$}\label{wxdbtableminusminus}
\func{bool}{operator $--$}{\void}
@ -3991,7 +3900,6 @@ Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
\helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
\section{\class{wxDbTableInf}}\label{wxdbtableinf}
\begin{verbatim}
@ -4002,7 +3910,6 @@ Synonym for \helpref{wxDbTable::GetPrev}{wxdbtablegetprev}
pColInf = NULL;
\end{verbatim}
Currently only used by \helpref{wxDb::GetCatalog}{wxdbgetcatalog} internally
and \helpref{wxDbInf}{wxdbinf} class, but may be used in future releases for
user functions. Contains information describing the table (Name, type, etc).
@ -4014,6 +3921,9 @@ structure.
Eventually, accessor functions will be added for this class
See the \helpref{database classes overview}{odbcoverview} for
an introduction to using the ODBC classes.
\membersection{wxDbTableInf::Initialize}\label{wxdbtableinfinitialize}
Simply initializes all member variables to a cleared state. Called by

101
docs/latex/wx/tdb.tex
View File

@ -10,7 +10,7 @@ is being done solely on the new wxDb/wxDbTable classes.}
\subsection{Different ODBC Class Libraries in wxWindows}
Following is detailed overview of how to use the wxWindows ODBC classes - \helpref{wxDb}{wxdb}
Following is a detailed overview of how to use the wxWindows ODBC classes - \helpref{wxDb}{wxdb}
and \helpref{wxDbTable}{wxdbtable} and their associated functions. These are
the ODBC classes donated by Remstar International, and are collectively
referred to herein as the wxODBC classes. Since their initial inclusion with
@ -32,11 +32,11 @@ Classes: \helpref{wxDb}{wxdb}, \helpref{wxDbTable}{wxdbtable}
The wxODBC classes were designed for database independence. Although SQL and
ODBC both have standards which define the minimum requirements they must
support to be in compliance with specifications, different database vendors
may implement things slightly different. One example of this is that Oracle
may implement things slightly differently. One example of this is that Oracle
requires all user names for the datasources to be supplied in uppercase
characters. In situations like this, the wxODBC classes have been written
to make this transparent to the programmer when using functions that require
database specific syntax.
database-specific syntax.
Currently several major databases, along with other widely used databases,
have been tested and supported through the wxODBC classes. The list of
@ -96,7 +96,7 @@ connection is not needed for each table (the exception is for isolating
commits/rollbacks on different tables from affecting more than the desired
table. See the class documentation on
\helpref{wxDb::CommitTrans}{wxdbcommittrans} and
\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.}
\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.)}
\twocolitem{Rows}{Similar to records in old relational databases, a row is a
collection of one instance of each column of the data table that are all
associated with each other.}
@ -110,7 +110,7 @@ satisfy the query, and creates a result set.}
in a query sent to the datasource. Dependent on drivers, a result set
typically remains at the datasource (no data is transmitted to the ODBC driver)
until the client actually instructs the ODBC driver to retrieve it.}
\twocolitem{Cursor}{a logical pointer into the result set that a query
\twocolitem{Cursor}{A logical pointer into the result set that a query
generates, indicating the next record that will be returned to the client
when a request for the next record is made.}
\twocolitem{Scrolling cursors}{Scrolling refers to the movement of cursors
@ -136,7 +136,7 @@ connection to the datasource are all committed/rolled back at the same
time when a call to
\helpref{wxDb::CommitTrans}{wxdbcommittrans} or
\helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} is made.}
\twocolitem{Index}{Indexes are datasource maintained lookup structures
\twocolitem{Index}{Indexes are datasource-maintained lookup structures
that allow the datasource to quickly locate data rows based on the values
of certain columns. Without indexes, the datasource would need to do a
sequential search of a table every time a query request is made. Proper
@ -173,10 +173,10 @@ For each result set, a cursor is maintained (typically by the database)
which keeps track of where in the result set the user currently is.
Depending on the database, ODBC driver, and how you configured the
wxWindows ODBC settings in setup.h (see \helpref{wxODBC - Compiling}{wxodbccompiling}), cursors can be
either forward or backward scrolling. At a minim, cursors must scroll
either forward or backward scrolling. At a minimum, cursors must scroll
forward. For example, if a query resulted in a result set with 100 rows,
as the data is read by the client application, it will read row 1, then 2,
then 3, etc, etc. With forward only cursors, once the cursor has moved to
then 3, etc. With forward only cursors, once the cursor has moved to
the next row, the previous row cannot be accessed again without re-querying
the datasource for the result set over again. Backward scrolling cursors
allow you to request the previous row from the result set, actually
@ -195,14 +195,14 @@ potentially large performance benefits can be gained from using them.
There is a limit to the number of cursors that can be open on each connection
to the datasource, and usually a maximum number of cursors for the datasource
itself. This is all dependent on the database. Each connection that is
opened (each instance of a wxDb) opens a minimum of 5 cursors for on creation
opened (each instance of a wxDb) opens a minimum of 5 cursors on creation
that are required for things such as updates/deletions/rollbacks/queries.
Cursors are a limited resource, so use care in creating large numbers of
cursors.
Additional cursors can be created if necessary with the
\helpref{wxDbTable::GetNewCursor}{wxdbtablegetnewcursor} function. One example
use for additional cursors are to track multiple scroll points in result
use for additional cursors is to track multiple scroll points in result
sets. By creating a new cursor, a program could request a second result set
from the datasource while still maintaining the original cursor position in
the first result set.
@ -214,10 +214,10 @@ datasource to tell the datasource that the action(s) it has been told to
perform are to be recorded as permanent. Until a commit is performed,
any other programs that query the datasource will not see the changes that
have been made (although there are databases that can be configured to
auto-commit). NOTE: With most all datasources, until the commit is
auto-commit). NOTE: With most datasources, until the commit is
performed, any cursor that is open on that same datasource connection
will be able to see the changes that are uncommitted. Check your
database's documentation/configuration to verify this before counting on it
database's documentation/configuration to verify this before relying on it
though.
A rollback is basically an UNDO command on the datasource connection. When
@ -230,8 +230,6 @@ shares the same connection, and a commit or rollback is done on that
connection, all pending changes for ALL tables using that connection are
committed/rolled back.
\subsection{wxODBC - Configuring your system for ODBC use}\label{wxodbcconfiguringyoursystem}
Before you are able to access a datasource, you must have installed and
@ -240,13 +238,13 @@ covered in detail here. But here are a few details to get you started.
Most database vendors provide at least a minimal ODBC driver with their
database product. In practice, many of these drivers have proven to be slow
and/or incomplete. Rumor has it that this is because the vendors do not want
you using the ODBC interface to their products, they want you to use their
and/or incomplete. Rumour has it that this is because the vendors do not want
you using the ODBC interface to their products; they want you to use their
applications to access the data.
Whatever the reason, for database intensive applications, you may want to
think of using a third-party ODBC driver for your needs. One example of a
third party set of ODBC drivers that has been heavily tested and used is
Whatever the reason, for database-intensive applications, you may want to
consider using a third-party ODBC driver for your needs. One example of a
third-party set of ODBC drivers that has been heavily tested and used is
Rogue Wave's drivers. Rogue Wave has drivers available for many different
platforms and databases.
@ -256,11 +254,11 @@ instance of the driver for your intended datasource. Note that with all
flavors of NT, this configuration can be set up as a System or User DSN
(datasource name). Configuring it as a system resource will make it
available to all users (if you are logged in as 'administrator'), otherwise
the datasource will only be available to the who configured the DSN.
the datasource will only be available to the user who configured the DSN.
Under Unix, iODBC is used for implementation of the ODBC API. To compile the
wxODBC classes, you must first obtain (http://www.iodbc.org) and install iODBC.
Then you must create the file "~/.odbc.ini" (or optionally create
wxODBC classes, you must first obtain iODBC from \urlref{http://www.iodbc.org}{www.iodbc.org} and install it.
(Note: wxWindows currently includes a version of iODBC.) Then you must create the file "~/.odbc.ini" (or optionally create
"/etc/odbc.ini" for access for all users on the system). This file contains
the settings for your system/datasource. Below is an example section of a
odbc.ini file for use with the "samples/db" sample program using MySQL:
@ -277,8 +275,6 @@ odbc.ini file for use with the "samples/db" sample program using MySQL:
PORT = 3306
\end{verbatim}
\subsection{wxODBC - Compiling}\label{wxodbccompiling}
The wxWindows setup.h file has several settings in it pertaining to compiling
@ -324,8 +320,6 @@ You cannot compile the wxODBC classes under Win16 - sorry.
\normalbox{MORE TO COME}
\subsection{wxODBC - Basic Step-By-Step Guide}\label{wxodbcstepbystep}
To use the classes in an application, there are eight basic steps:
@ -344,12 +338,11 @@ To use the classes in an application, there are eight basic steps:
Following each of these steps is detailed to explain the step, and to
hopefully mention as many of the pitfalls that beginning users fall in
to when first starting to use the classes. Throughout the steps, small
snippets of code are shown to show the syntax of performing the step. A
snippets of code are provided to show the syntax of performing the step. A
complete code snippet is provided at the end of this overview that shows a
complete working flow of all these steps (see
\helpref{wxODBC - Sample Code {\tt\#}1}{wxodbcsamplecode1}).
{\bf Define datasource connection information}
To be able to connect to a datasource through the ODBC driver, a program must
@ -396,7 +389,6 @@ they will be used to write our own ODBC Administrator type program that will
work on both MSW and Un*x systems, regardless of the datasource. Very little
work has been done on this to date.
{\bf Get a Datasource Connection}
There are two methods of establishing a connection to a datasource. You
@ -467,12 +459,12 @@ the members of the wxDb class. The second line actually sends the request
to the ODBC driver to open a connection to its associated datasource using
the parameters supplied in the call to \helpref{wxDb::Open}{wxdbopen}.
A more advanced form of opening a connection is to used the connection
A more advanced form of opening a connection is to use the connection
caching functions that are included with the wxODBC classes. The caching
mechanisms do the same functions are the manual approach to opening a
mechanisms perform the same functions as the manual approach to opening a
connection, but they also manage each connection they have created,
re-using them and cleaning them up when they are closed, without you
programmatically needing to do the coding.
needing to do the coding.
To use the caching function \helpref{wxDbGetConnection}{wxdbfunctions} to get
a connection to a datasource, simply call it with a single parameter of the
@ -489,8 +481,8 @@ from \helpref{wxDbGetConnection}{wxdbfunctions} will be NULL.
The connection that is returned is either a new connection, or it is a
"free" connection from the cache of connections that the class maintains
that was no longer in use. Any wxDb instance created with a call to
\helpref{wxDbGetConnection}{wxdbfunctions} is kept track of in a linked list of established
connections. When a program is done with a connection, a call to
\helpref{wxDbGetConnection}{wxdbfunctions} is recorded in a linked list of established
connections. When a program is finished with a connection, a call to
\helpref{wxDbFreeConnection}{wxdbfunctions} is made, and the datasource
connection will then be tagged as FREE, making it available for the next
call to \helpref{wxDbGetConnection}{wxdbfunctions} that needs a connection
@ -503,14 +495,14 @@ obtain a datasource connection, using cached connections can be quite a
performance boost as well. Each time that a new connection is created
(not retrieved from the cache of free connections), the wxODBC classes
perform many queries against the datasource to determine the datasource's
datatypes and other fundamental behaviors. Depending on the hardware,
datatypes and other fundamental behaviours. Depending on the hardware,
network bandwidth, and datasource speed, this can in some cases take a
few seconds to establish the new connection (with well balanced systems,
few seconds to establish the new connection (with well-balanced systems,
it should only be a fraction of a second). Re-using already established
datasource connections rather than creating/deleting, creating/deleting
connections can be quite a time saver.
connections can be quite a time-saver.
Another time saver is the "copy connection" features of both
Another time-saver is the "copy connection" features of both
\helpref{wxDb::Open}{wxdbopen} and \helpref{wxDbGetConnection}{wxdbfunctions}.
If manually creating a wxDb instance and opening it, you must pass an existing
connection to the \helpref{wxDb::Open}{wxdbopen} function yourself to gain the performance
@ -524,7 +516,7 @@ queried, rather than re-querying the datasource for all those same settings.
One final note on creating a connection. When a connection is created, it
will default to only allowing cursor scrolling to be either forward only,
or both backward and forward scrolling cursors. The default behavior is
or both backward and forward scrolling. The default behavior is
determined by the setting {\tt wxODBC\_FWD\_ONLY\_CURSORS} in setup.h when you
compile the wxWindows library. The library default is to only support
forward scrolling cursors only, though this can be overridden by parameters
@ -538,7 +530,6 @@ blurb about "Scrolling cursors" in the definitions at the beginning of
this overview, or other details of setting the cursor behavior in the wxDb
class documentation.
{\bf Create Table Definition}
Data can be accessed in a datasource's tables directly through various
@ -565,8 +556,8 @@ connecting to the datasource.
Each of the above parameters are described in detail in the wxDbTable
class' description, but one special note here about the fifth
parameter - queryOnly setting. If a wxDbTable instance is created as
{\tt wxDB\_QUERY\_ONLY}, then no inserts/deletes/updates are able to be performed
parameter - the queryOnly setting. If a wxDbTable instance is created as
{\tt wxDB\_QUERY\_ONLY}, then no inserts/deletes/updates can be performed
using this instance of the wxDbTable. Any calls to \helpref{wxDb::CommitTrans}{wxdbcommittrans}
or \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} against the datasource
connection used by this wxDbTable instance are ignored by this instance. If
@ -625,12 +616,11 @@ You may have as many wxDbTable instances accessing the same table using the
same wxDb instance as you desire. There is no limit imposed by the classes
on this. All datasources supported (so far) also have no limitations on this.
{\bf Open the table}
Opening the table technically is not doing anything with the datasource
Opening the table is not technically doing anything with the datasource
itself. Calling \helpref{wxDbTable::Open}{wxdbtableopen} simply does all the
house keeping of checking that the specified table exists, that the current
housekeeping of checking that the specified table exists, that the current
connected user has at least SELECT privileges for accessing the table,
setting up the requisite cursors, binding columns and cursors, and
constructing the default INSERT statement that is used when a new row is
@ -643,14 +633,13 @@ inserted into the table (non-wxDB\_QUERY\_ONLY tables only).
}
\end{verbatim}
The only reason that a call to \helpref{wxDbTable::Open}{wxdbtableopen} will likely fail is if the
The only reason that a call to \helpref{wxDbTable::Open}{wxdbtableopen} is likely to fail is if the
user has insufficient privileges to even SELECT the table. Other problems
could occur, such as being unable to bind columns, but these other reason
point to some lack of resource (like memory). Any errors generated
internally in the \helpref{wxDbTable::Open}{wxdbtableopen} function are logged to the error log
if SQL logging is turned on for the classes.
{\bf Use the table}
To use the table and the definitions that are now set up, we must first
@ -724,7 +713,7 @@ can be retrieved:
Typically, when an error occurs when calling \helpref{wxDbTable::Query}{wxdbtablequery}, it is a
syntax problem in the WHERE clause that was specified. The exact SQL
(datasource specific) reason for what caused the failure of \helpref{wxDbTable::Query}{wxdbtablequery}
(datasource-specific) reason for what caused the failure of \helpref{wxDbTable::Query}{wxdbtablequery}
(and all other operations against the datasource can be found by
parsing the table's database connection's "errorList[]" array member for
the stored text of the error.
@ -735,7 +724,7 @@ provided criteria. This does not mean that there are any rows in the
result set, it just mean that the query was successful.
\normalbox{IMPORTANT: The result created by the call to
\helpref{wxDbTable::Query}{wxdbtablequery} can be one of two forms. It is
\helpref{wxDbTable::Query}{wxdbtablequery} can take one of two forms. It is
either a snapshot of the data at the exact moment that the database
determined the record matched the search criteria, or it is a pointer to
the row that matched the selection criteria. Which form of behavior is
@ -743,7 +732,7 @@ datasource dependent. If it is a snapshot, the data may have changed
since the result set was constructed, so beware if your datasource
uses snapshots and call \helpref{wxDbTable::Refresh}{wxdbtablerefresh}. Most larger brand databases
do not use snapshots, but it is important to mention so that your application
can handle it properly if your datasource does. }
can handle it properly if your datasource does.}
To retrieve the data, one of the data fetching routines must be used to
request a row from the result set, and to store the data from the result
@ -775,7 +764,6 @@ no rows remaining in the result set after the current cursor position,
\helpref{wxDbTable::GetNext}{wxdbtablegetnext} (as well as all the other
wxDbTable::GetXxxxx() functions) will return FALSE.
{\bf Close the table}
When the program is done using a wxDbTable instance, it is as simple as
@ -796,12 +784,10 @@ column definitions and frees the SQL environment handles used by the
table (but not the environment handle used by the datasource connection
that the wxDbTable instance was using).
{\bf Close the datasource connection}
After all tables that have been using a datasource connection have been
closed (this can be checked by calling \helpref{wxDb::GetTableCount}{wxdbgettablecount}
closed (this can be verified by calling \helpref{wxDb::GetTableCount}{wxdbgettablecount}
and checking that it returns 0), then you may close the datasource
connection. The method of doing this is dependent on whether the
non-caching or caching method was used to obtain the datasource connection.
@ -839,7 +825,6 @@ environment handle), do the following:
wxDbCloseConnections();
\end{verbatim}
{\bf Release the ODBC environment handle}
Once all of the connections that used the ODBC environment handle (in
@ -861,7 +846,6 @@ wxDbConnectInf will free the handle automatically.
\normalbox{Remember to never release this environment handle if there are any
connections still using the handle.}
\subsection{wxODBC - Known Issues}\label{wxodbcknownissues}
As with creating wxWindows, writing the wxODBC classes was not the simple
@ -890,7 +874,6 @@ for additional databases in the future requires adding an entry for the
database in the \helpref{wxDb::Dbms}{wxdbdbms} function, and then handling any error codes
returned by the datasource that do not match the expected values.
{\bf Databases}
Following is a list of known issues and incompatibilities that the
@ -949,7 +932,6 @@ functionality as the driver can emulate.
\item Columns which are part of a primary key must be declared as NOT NULL
\end{itemize}
{\bf UNICODE with wxODBC classes}
The ODBC classes support for Unicode is yet in early experimental stage and
@ -1218,7 +1200,6 @@ Class: \helpref{wxRecordSet}{wxrecordset}
Use \helpref{wxDb}{wxdb} and \helpref{wxDbTable}{wxdbtable} instead.
Each wxRecordSet represents a database query. You can make multiple queries
at a time by using multiple wxRecordSets with a wxDatabase or you can make
your queries in sequential order using the same wxRecordSet.
@ -1347,5 +1328,3 @@ Example:
This example sets a field in column `X' to the number 123, for the record
where the column ASSET has the value `BD34'.