latex/wx/db.tex

1 \section{\class{wxDb}}\label{wxdb}
3 A wxDb instance is a connection to an ODBC datasource which may
18 The following classes and structs are defined in db.cpp/.h for use with the wxDb class.
67 These are the databases currently tested and working with the ODBC classes.  A call to \helpref{wxDb::Dbms}{wxdbdbms} will return one of these enumerated values listed below.
86 See the remarks in \helpref{wxDb::Dbms}{wxdbdbms} for exceptions/issues with each of these database engines.
90 \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.}
92 \docparam{int {\bf wxDb::DB\_STATUS}}{The last ODBC error/status that occurred on this data connection.  Possible codes are:}
186 \docparam{struct {\bf wxDb::dbInf}}{This structure is internal to the
187 wxDb class and contains details of the ODBC datasource that the current
188 instance of the wxDb is connected to in its members.  When the datasource
242 \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.}
244 \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.}
246 \docparam{SDWORD {\bf wxDb::nativeError}}{Set by wxDb::DispAllErrors,
247 wxDb::GetNextError, and wxDb::DispNextError.  It contains the
251 \docparam{wxChar {\bf wxDb::sqlState}[20]}{Set by wxDb::TranslateSqlState().
259 an instance of a wxDb is created (see \helpref{wxDb constructor}{wxdbctor}).
271 The following functions are used in conjunction with the wxDb class.
285 This function performs a \helpref{wxDb::CommitTrans}{wxdbcommittrans}
300 \func{bool}{wxDbFreeConnection}{\param{wxDb *}{pDb}}
305 the passed in wxDb instance.  If found, that cached connection is freed.
309 is able to return a pointer to the wxDb instance for use.  Freeing a
314 \func{wxDb *}{wxDbGetConnection}{\param{wxDbConnectInf *}{pDbConfig},
319 This function is used to request a "new" wxDb instance for use by the program.
320 The wxDb instance returned is also opened (see \helpref{wxDb::Open}{wxdbopen}).
323 maintain a cache of wxDb instances for user/re-use by a program.  When a
324 program needs a wxDb instance, it may call this function to obtain a wxDb
325 instance.  If there is a wxDb instance in the cache that is currently unused
328 the wxDb instance is returned.
331 given in {\it'pDbConfig'}, then a new wxDb instance is created to connect
335 NOTE: The caching routine also uses the \helpref{wxDb::Open}{wxdbopen}
348 the wxDb instance back to the cache.  DO NOT DELETE THE wxDb INSTANCE!
349 Deleting the wxDb instance returned can cause a crash/memory corruption
356 \func{const wxChar *}{wxDbLogExtendedErrorMsg}{\param{const wxChar *}{userText}, \param{wxDb *}{pDb}, \param{wxChar *}{ErrFile}, \param{int }{ErrLine}}
365 This function sets the sql log state for all open wxDb objects
384 \membersection{wxDb::wxDb}\label{wxdbctor}
386 \func{}{wxDb}{\void}
390 \func{}{wxDb}{\param{const HENV \&}{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}
404 This is the constructor for the wxDb class.  The wxDb object must
413    wxDb sampleDB(ConnectInf.GetHenv());
425 \membersection{wxDb::Catalog}\label{wxdbcatalog}
461 \membersection{wxDb::Close}\label{wxdbclose}
485    // Close the wxDb connection when finished with it
490 \membersection{wxDb::CommitTrans}\label{wxdbcommittrans}
514 Until a call to wxDb::CommitTrans() is made, no other user or cursor is able
540 \membersection{wxDb::CreateView}\label{wxdbcreateviews}
583 \membersection{wxDb::Dbms}\label{wxdbdbms}
597 \helpref{Enumerated types}{wxdbenumeratedtypes} section of wxDb.
610 \membersection{wxDb::DispAllErrors}\label{wxdbdispallerrors}
617 is turned on via \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, then an
645 \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, wxDbSqlLog
655 \membersection{wxDb::DispNextError}\label{wxdbdispnexterror}
663 function works in conjunction with \helpref{wxDb::GetNextError}{wxdbgetnexterror} when errors (or
666 the next ODBC error from the ODBC error queue.  The wxDb member variables
696 \membersection{wxDb::DropView}\label{wxdbdropview}
710 \membersection{wxDb::EscapeSqlChars}\label{wxdbescapesqlchars}
729 \membersection{wxDb::ExecSql}\label{wxdbexecsql}
749 This member extends the wxDb class and allows you to build and execute ANY VALID
756 \helpref{wxDb::GetData}{wxdbgetdata}, \helpref{wxDb::GetNext}{wxdbgetnext}
758 \membersection{wxDb::FwdOnlyCursors}\label{wxdbfwdonlycursors}
763 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}.  This method is
765 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors} should be
771 \membersection{wxDb::GetCatalog}\label{wxdbgetcatalog}
794 \membersection{wxDb::GetColumnCount}\label{wxdbgetcolumncount}
818 \membersection{wxDb::GetColumns}\label{wxdbgetcolumns}
847 \normalbox{ALL column bindings associated with this wxDb instance are unbound
849 this wxDb instance.  This function should use its own wxDb instance
870 \membersection{wxDb::GetData}\label{wxdbgetdata}
892 \helpref{wxDb::GetData}{wxdbgetdata} call has failed.}
896 \helpref{wxDb::GetNext}{wxdbgetnext}, \helpref{wxDb::ExecSql}{wxdbexecsql}
940 \membersection{wxDb::GetDatabaseName}\label{wxdbgetdatabasename}
946 \membersection{wxDb::GetDatasourceName}\label{wxdbgetdatasourcename}
952 \membersection{wxDb::GetHDBC}\label{wxdbgethdbc}
958 \membersection{wxDb::GetHENV}\label{wxdbgethenv}
964 \membersection{wxDb::GetHSTMT}\label{wxdbgethstmt}
970 \membersection{wxDb::GetKeyFields}\label{wxdbgetkeyfields}
976 This function is primarily for use by the \helpref{wxDb::GetColumns}{wxdbgetcolumns} function, but may be called if desired from the client application.
981 \docparam{colInf}{Data structure containing the column definitions (obtained with \helpref{wxDb::GetColumns}{wxdbgetcolumns}).  This function populates the PkCol, PkTableName, and FkTableName members of the colInf structure.}
990 \helpref{wxDbColInf}{wxdbcolinf}, \helpref{wxDb::GetColumns}{wxdbgetcolumns}
992 \membersection{wxDb::GetNext}\label{wxdbgetnext}
1001 \helpref{wxDb::ExecSql}{wxdbexecsql}, \helpref{wxDb::GetData}{wxdbgetdata}
1003 \membersection{wxDb::GetNextError}\label{wxdbgetnexterror}
1028 \helpref{wxDb::DispNextError}{wxdbdispnexterror},
1029 \helpref{wxDb::DispAllErrors}{wxdbdispallerrors}
1032 \membersection{wxDb::GetPassword}\label{wxdbgetpassword}
1039 \membersection{wxDb::GetTableCount}\label{wxdbgettablecount}
1047 \membersection{wxDb::GetUsername}\label{wxdbgetusername}
1055 \membersection{wxDb::Grant}\label{wxdbgrant}
1094 \membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}
1105 If a wxDb instance was created as being capable of only forward scrolling
1110 The default setting of whether a wxDb connection to a database allows
1113 when the wxDb connection is initially created (see
1114 \helpref{wxDb constructor}{wxdbctor} and \helpref{wxDbGetConnection}{wxdbfunctions}).
1125 wxDb::FwdOnlyCursors() to match the normal wxWidgets naming conventions for
1129 use \helpref{wxDb::FwdOnlyCursors}{wxdbfwdonlycursors} for wxWidgets
1134 \helpref{wxDb constructor}{wxdbctor}, \helpref{wxDbGetConnection}{wxdbfunctions}
1136 \membersection{wxDb::IsOpen}\label{wxdbisopen}
1146 the call to \helpref{wxDb::Open}{wxdbopen} may have failed to fully
1150 \helpref{wxDb::Open}{wxdbopen} to have completed correctly may not function
1151 as expected.  The return result from \helpref{wxDb::Open}{wxdbopen} is the
1152 only way to know if complete initialization of this wxDb connection was
1153 successful or not.  See \helpref{wxDb::Open}{wxdbopen} for more details on
1156 \membersection{wxDb::LogError}\label{wxdblogerror}
1174 \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog}
1176 \membersection{wxDb::ModifyColumn}\label{wxdbmodifycolumn}
1213 \membersection{wxDb::Open}\label{wxdbopen}
1224 \func{bool}{Open}{\param{wxDb *}{copyDb}}
1232 The second form of this function, which accepts a "wxDb *" as a parameter,
1237 Normally the first form of the wxDb::Open() function will open the connection
1243 connection in as a parameter to the wxDb::Open() function.  Note that this
1260 wxDb::Open() function will query the database to find out the native types
1276 originally, then the connection being made by this call to wxDb::Open() will
1281 After a wxDb instance is created, it must then be opened.  When opening a
1290 of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.
1296 if the connection to the database failed, use the \helpref{wxDb::IsOpen}{wxdbisopen}
1298 the connection was opened or not.  If this function returns false, but \helpref{wxDb::IsOpen}{wxdbisopen}
1306 must maintain the memory for these three strings for the life of the wxDb instance.}
1311    wxDb sampleDB(DbConnectInf.GetHenv());
1326 \membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}
1330 Function to "undo" changes made to the database.  After an insert/update/delete, the operation may be "undone" by issuing this command any time before a \helpref{wxDb::CommitTrans}{wxdbcommittrans} is called on the database connection.
1336 wxDb::RollbackTrans() will result in ALL changes done using this database
1346 \helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors
1348 \membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
1366 \helpref{wxDb constructor}{wxdbctor}
1368 \membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
1380 When called with {\it sqlLogON}, all commands sent to the datasource engine are logged to the file specified by {\it filename}.  Logging is done by embedded \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} calls in the database member functions, or may be manually logged by adding calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} in your own source code.
1382 When called with {\it sqlLogOFF}, the logging file is closed, and any calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} are ignored.
1384 \membersection{wxDb::SQLColumnName}\label{wxdbsqlcolumnname}
1404 \helpref{wxDb::SQLTableName}{wxdbsqltablename}
1406 \membersection{wxDb::SQLTableName}\label{wxdbsqltablename}
1426 \helpref{wxDb::SQLColumnName}{wxdbsqlcolumnname}
1428 \membersection{wxDb::TableExists}\label{wxdbtableexists}
1453 This function does not indicate whether or not the user has privileges to query or perform other functions on the table.  Use the \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} to determine if the user has sufficient privileges or not.
1457 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
1459 \membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}
1537 \membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}
1549 Returns the internal class DB\_ERR code.  See \helpref{wxDb::DB\_STATUS}{wxdb} definition.
1551 \membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
1562 (see \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging} for details on
1574 \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
1596 object.  When calling the \helpref{wxDb constructor}{wxdbctor}, a
1633 \helpref{wxDbTable::GetColDefs}{wxdbtablegetcoldefs}, \helpref{wxDb constructor}{wxdbctor}
1700 Used with the \helpref{wxDb::GetColumns}{wxdbgetcolumns} functions for obtaining all retrievable information about a column's definition.
1789 \docparam{dsn}{Name of the datasource to be used in creating wxDb instances
2124 \func{}{wxDbTable}{\param{wxDb *}{pwxDb}, \param{const wxString \&}{tblName},
2132 \docparam{pwxDb}{Pointer to the wxDb instance to be used by this wxDbTable
2537 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2576 be the user id that was given when \helpref{wxDb::Open}{wxdbopen} was called.
2586 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2593 Accessor function that returns the wxDb private member variable DB\_STATUS for
2611 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2612 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
2617 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2618 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2667 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2668 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
2680 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2681 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2721 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} must be called after use of
2729 without performing a \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
2730 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans}.  Size of the rollback
2767 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2779 supported databases (see \helpref{wxDb::Dbms}{wxdbdbms}).  If a datasource
2787 It is not necessary to call \helpref{wxDb::CommitTrans}{wxdbcommittrans}
2860 \func{wxDb *}{GetDb}{}
2885 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
2918 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}
3012 \helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors},
3094 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3095 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3211 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} function
3217 \helpref{wxDb::TableExists}{wxdbtableexists},
3218 \helpref{wxDb::TablePrivileges}{wxdbtableprivileges}
3653 \helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
3656 \helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
3920 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3921 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
3952 A \helpref{wxDb::CommitTrans}{wxdbcommittrans} or
3953 \helpref{wxDb::RollbackTrans}{wxdbrollbacktrans} must be called after use of
4015 Currently only used by \helpref{wxDb::GetCatalog}{wxdbgetcatalog} internally
4020 \helpref{wxDb::GetColumns}{wxdbgetcolumns})