X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cc81d32f2bf8c159f3b1bf6ddaf62e6d77720209..d3e78bab3ea46183c22a5f0484b931a99b897636:/docs/latex/wx/tdb.tex?ds=sidebyside diff --git a/docs/latex/wx/tdb.tex b/docs/latex/wx/tdb.tex index 4ff6da4cc9..7a2d7be7fc 100644 --- a/docs/latex/wx/tdb.tex +++ b/docs/latex/wx/tdb.tex @@ -1,29 +1,9 @@ \section{Database classes overview}\label{odbcoverview} -\normalboxd{The more sophisticated wxODBC classes (wxDb/wxDbTable) are the -recommended classes for doing database/ODBC work with wxWindows. These new -classes replace the wxWindows v1.6x classes wxDatabase. Documentation for the -old wxDatabase class and its associated classes is still -included in the class documentation and in this overview section, but support -for these old classes has been phased out, and all future development work -is being done solely on the new wxDb/wxDbTable classes.} - -\subsection{Different ODBC Class Libraries in wxWindows} - 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 -wxWindows v2.x, they have become the recommended wxWindows classes for database -access. - -An older version of some classes ported over from wxWindows v1.68 still exist -(see \helpref{wxDatabase}{wxdatabase} in odbc.cpp), but are now deprecated in favor of the more -robust and comprehensive wxDb/wxDbTable classes. All current and future -feature development, as well as active debugging, are only being done on -the wxODBC classes. Documentation for the older classes is still provided -in this manual. The \helpref{wxDatabase overview}{wxdatabaseoverview} of the -older classes follows the overview of the new classes. +referred to herein as the wxODBC classes. \subsection{wxDb/wxDbTable wxODBC Overview}\label{wxodbcoverview} @@ -341,7 +321,7 @@ to when first starting to use the classes. Throughout the steps, small 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}). +\helpref{wxODBC - Sample Code}{wxodbcsamplecode1}). {\bf Define datasource connection information} @@ -938,7 +918,7 @@ The ODBC classes support for Unicode is yet in early experimental stage and hasn't been tested extensively. It might work for you or it might not: please report the bugs/problems you have encountered in the latter case. -\subsection{wxODBC - Sample Code {\tt\#}1}\label{wxodbcsamplecode1} +\subsection{wxODBC - Sample Code}\label{wxodbcsamplecode1} Simplest example of establishing/opening a connection to an ODBC datasource, binding variables to the columns for read/write usage, opening an @@ -997,9 +977,9 @@ table->SetColDefs(1, "LAST_NAME", DB_DATA_TYPE_VARCHAR, LastName, // Open the table for access table->Open(); -// Set the WHERE clause to limit the result set to only -// return all rows that have a value of 'GEORGE' in the -// FIRST_NAME column of the table. +// Set the WHERE clause to limit the result set to return +// all rows that have a value of 'GEORGE' in the FIRST_NAME +// column of the table. table->SetWhereClause("FIRST_NAME = 'GEORGE'"); // Result set will be sorted in ascending alphabetical @@ -1029,12 +1009,37 @@ while (table->GetNext()) wxMessageBox(msg, "Data", wxOK | wxICON_INFORMATION, NULL); } + +// +// Select the row which has FIRST_NAME of 'GEORGE' and LAST_NAME +// of 'TASKER', then delete the retrieved row +// +table->SetWhereClause("FIRST_NAME = 'GEORGE' and "LAST_NAME = 'TASKER'"); +if (table->Query()) +{ + table->Delete(); + + // Must commit the deletion + table->GetDb()->CommitTrans(); +} + + +// +// Insert a new row into the table +// +wxStrcpy(FirstName, "JULIAN"); +wxStrcpy(LastName, "SMART"); +table->Insert(); + +// Must commit the insert +table->GetDb()->CommitTrans(); + + // If the wxDbTable instance was successfully created -// then delete it as I am done with it now. +// then delete it as we are done with it now. if (table) { - delete table; - table = NULL; + wxDelete(table); } // If we have a valid wxDb instance, then free the connection @@ -1054,198 +1059,11 @@ wxDbCloseConnections(); // Release the environment handle that was created // for use with the ODBC datasource connections -delete DbConnectInf; +wxDelete(DbConnectInf); \end{verbatim} -\subsection{wxDatabase ODBC class overview [DEPRECATED]}\label{oldwxodbcoverview} - -Classes: \helpref{wxDatabase}{wxdatabase}, \helpref{wxRecordSet}{wxrecordset}, \helpref{wxQueryCol}{wxquerycol}, -\rtfsp\helpref{wxQueryField}{wxqueryfield} - -\normalboxd{The more sophisticated wxODBC classes (wxDb/wxDbTable) are the -recommended classes for doing database/ODBC work with wxWindows. These new -classes replace the wxWindows v1.6x classes wxDatabase. - -Documentation for the old wxDatabase class and its associated classes is still -included in the class documentation and in this overview section, but support -for these old classes has been phased out, and all future development work -is being done solely on the new wxDb/wxDbTable classes.} - -wxWindows provides a set of classes for accessing a subset of Microsoft's ODBC (Open Database Connectivity) -product. Currently, this wrapper is available under MS Windows only, although -ODBC may appear on other platforms, and a generic or product-specific SQL emulator for the ODBC -classes may be provided in wxWindows at a later date. - -ODBC presents a unified API (Application Programmer's Interface) to a -wide variety of databases, by interfacing indirectly to each database or -file via an ODBC driver. The language for most of the database -operations is SQL, so you need to learn a small amount of SQL as well as -the wxWindows ODBC wrapper API. Even though the databases may not be -SQL-based, the ODBC drivers translate SQL into appropriate operations -for the database or file: even text files have rudimentary ODBC support, -along with dBASE, Access, Excel and other file formats. - -The run-time files for ODBC are bundled with many existing database -packages, including MS Office. The required header files, sql.h and -sqlext.h, are bundled with several compilers including MS VC++ and -Watcom C++. The only other way to obtain these header files is from the -ODBC SDK, which is only available with the MS Developer Network CD-ROMs --- at great expense. If you have odbc.dll, you can make the required -import library odbc.lib using the tool `implib'. You need to have odbc.lib -in your compiler library path. - -The minimum you need to distribute with your application is odbc.dll, which must -go in the Windows system directory. For the application to function correctly, -ODBC drivers must be installed on the user's machine. If you do not use the database -classes, odbc.dll will be loaded but not called (so ODBC does not need to be -setup fully if no ODBC calls will be made). - -A sample is distributed with wxWindows in {\tt samples/odbc}. You will need to install -the sample dbf file as a data source using the ODBC setup utility, available from -the control panel if ODBC has been fully installed. - -\subsection{Procedures for writing an ODBC application using wxDatabase [DEPRECATED]} - -You first need to create a wxDatabase object. If you want to get information -from the ODBC manager instead of from a particular database (for example -using \helpref{wxRecordSet::GetDataSources}{wxrecordsetgetdatasources}), then you -do not need to call \helpref{wxDatabase::Open}{wxdatabaseopen}. -If you do wish to connect to a datasource, then call wxDatabase::Open. -You can reuse your wxDatabase object, calling wxDatabase::Close and wxDatabase::Open -multiple times. - -Then, create a wxRecordSet object for retrieving or sending information. -For ODBC manager information retrieval, you can create it as a dynaset (retrieve the -information as needed) or a snapshot (get all the data at once). -If you are going to call \helpref{wxRecordSet::ExecuteSQL}{wxrecordsetexecutesql}, you need to create it as a snapshot. -Dynaset mode is not yet implemented for user data. - -Having called a function such as wxRecordSet::ExecuteSQL or -wxRecordSet::GetDataSources, you may have a number of records -associated with the recordset, if appropriate to the operation. You can -now retrieve information such as the number of records retrieved and the -actual data itself. Use \helpref{wxRecordSet::GetFieldData}{wxrecordsetgetfielddata} or -\helpref{wxRecordSet::GetFieldDataPtr}{wxrecordsetgetfielddataptr} to get the data or a pointer to it, passing -a column index or name. The data returned will be for the current -record. To move around the records, use \helpref{wxRecordSet::MoveNext}{wxrecordsetmovenext}, -\rtfsp\helpref{wxRecordSet::MovePrev}{wxrecordsetmoveprev} and associated functions. - -You can use the same recordset for multiple operations, or delete -the recordset and create a new one. - -Note that when you delete a wxDatabase, any associated recordsets -also get deleted, so beware of holding onto invalid pointers. - -\subsection{wxDatabase class overview [DEPRECATED]}\label{wxdatabaseoverview} - -Class: \helpref{wxDatabase}{wxdatabase} - -\wxheading{DEPRECATED} - -Use \helpref{wxDb}{wxdb} and \helpref{wxDbTable}{wxdbtable} instead. - -Every database object represents an ODBC connection. To do anything useful -with a database object you need to bind a wxRecordSet object to it. All you -can do with wxDatabase is opening/closing connections and getting some info -about it (users, passwords, and so on). - -\wxheading{See also} - -\helpref{Database classes overview}{odbcoverview} - -\subsection{wxQueryCol class overview [DEPRECATED]}\label{wxquerycoloverview} - -Class: \helpref{wxQueryCol}{wxquerycol} - -\wxheading{DEPRECATED} - -Use \helpref{wxDb}{wxdb} and \helpref{wxDbTable}{wxdbtable} instead. - -Every data column is represented by an instance of this class. -It contains the name and type of a column and a list of wxQueryFields where -the real data is stored. The links to user-defined variables are stored -here, as well. - -\wxheading{See also} - -\helpref{Database classes overview}{odbcoverview} - -\subsection{wxQueryField class overview [DEPRECATED]}\label{wxqueryfieldoverview} - -Class: \helpref{wxQueryField}{wxqueryfield} - -\wxheading{DEPRECATED} - -Use \helpref{wxDb}{wxdb} and \helpref{wxDbTable}{wxdbtable} instead. - -As every data column is represented by an instance of the class wxQueryCol, -every data item of a specific column is represented by an instance of -wxQueryField. Each column contains a list of wxQueryFields. If wxRecordSet is -of the type wxOPEN\_TYPE\_DYNASET, there will be only one field for each column, -which will be updated every time you call functions like wxRecordSet::Move -or wxRecordSet::GoTo. If wxRecordSet is of the type wxOPEN\_TYPE\_SNAPSHOT, -all data returned by an ODBC function will be loaded at once and the number -of wxQueryField instances for each column will depend on the number of records. - -\wxheading{See also} - -\helpref{Database classes overview}{odbcoverview} - -\subsection{wxRecordSet overview [DEPRECATED]}\label{wxrecordsetoverview} - -Class: \helpref{wxRecordSet}{wxrecordset} - -\wxheading{DEPRECATED} - -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. - -\wxheading{See also} - -\helpref{Database classes overview}{odbcoverview} - -\subsection{ODBC SQL data types [DEPRECATED]}\label{sqltypes} - -These are the data types supported in ODBC SQL. Note that there are other, extended level conformance -types, not currently supported in wxWindows. - -\begin{twocollist}\itemsep=0pt -\twocolitem{CHAR(n)}{A character string of fixed length {\it n}.} -\twocolitem{VARCHAR(n)}{A varying length character string of maximum length {\it n}.} -\twocolitem{LONG VARCHAR(n)}{A varying length character string: equivalent to VARCHAR for the purposes -of ODBC.} -\twocolitem{DECIMAL(p, s)}{An exact numeric of precision {\it p} and scale {\it s}.} -\twocolitem{NUMERIC(p, s)}{Same as DECIMAL.} -\twocolitem{SMALLINT}{A 2 byte integer.} -\twocolitem{INTEGER}{A 4 byte integer.} -\twocolitem{REAL}{A 4 byte floating point number.} -\twocolitem{FLOAT}{An 8 byte floating point number.} -\twocolitem{DOUBLE PRECISION}{Same as FLOAT.} -\end{twocollist} - -These data types correspond to the following ODBC identifiers: - -\begin{twocollist}\itemsep=0pt -\twocolitem{SQL\_CHAR}{A character string of fixed length.} -\twocolitem{SQL\_VARCHAR}{A varying length character string.} -\twocolitem{SQL\_DECIMAL}{An exact numeric.} -\twocolitem{SQL\_NUMERIC}{Same as SQL\_DECIMAL.} -\twocolitem{SQL\_SMALLINT}{A 2 byte integer.} -\twocolitem{SQL\_INTEGER}{A 4 byte integer.} -\twocolitem{SQL\_REAL}{A 4 byte floating point number.} -\twocolitem{SQL\_FLOAT}{An 8 byte floating point number.} -\twocolitem{SQL\_DOUBLE}{Same as SQL\_FLOAT.} -\end{twocollist} - -\wxheading{See also} - -\helpref{Database classes overview}{odbcoverview} - -\subsection{A selection of SQL commands [DEPRECATED]}\label{sqlcommands} +\subsection{A selection of SQL commands}\label{sqlcommands} The following is a very brief description of some common SQL commands, with examples.