X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6b2878de13d4159bbb399c862b00762a94f07be7..8b0f8432d72fc44aa7247ab1c19c04103323feea:/docs/latex/wx/tdb.tex diff --git a/docs/latex/wx/tdb.tex b/docs/latex/wx/tdb.tex index 449efdbfc3..b70ebba29d 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} @@ -404,8 +384,8 @@ member. \begin{verbatim} wxDbConnectInf DbConnectInf; - DbConnectInf.SetDsn,"MyDSN"); - DbConnectInf.SetUserID,"MyUserName"); + DbConnectInf.SetDsn("MyDSN"); + DbConnectInf.SetUserID("MyUserName"); DbConnectInf.SetPassword("MyPassword"); DbConnectInf.SetDefaultDir(""); \end{verbatim} @@ -424,7 +404,7 @@ the necessary handle: \end{verbatim} When the wxDbConnectInf::AllocHenv() function is called successfully, a -value of TRUE will be returned. A value of FALSE means allocation failed, +value of true will be returned. A value of false means allocation failed, and the handle will be undefined. A shorter form of doing the above steps is encapsulated into the @@ -579,9 +559,9 @@ can specify anywhere from one column up to all columns in the table. \begin{verbatim} table->SetColDefs(0, "FIRST_NAME", DB_DATA_TYPE_VARCHAR, FirstName, - SQL_C_CHAR, sizeof(name), TRUE, TRUE); + SQL_C_CHAR, sizeof(name), true, true); table->SetColDefs(1, "LAST_NAME", DB_DATA_TYPE_VARCHAR, LastName, - SQL_C_CHAR, sizeof(LastName), TRUE, TRUE); + SQL_C_CHAR, sizeof(LastName), true, true); \end{verbatim} Notice that column definitions start at index 0 and go up to one less than @@ -718,7 +698,7 @@ syntax problem in the WHERE clause that was specified. The exact SQL parsing the table's database connection's "errorList[]" array member for the stored text of the error. -When the \helpref{wxDbTable::Query}{wxdbtablequery} returns TRUE, the +When the \helpref{wxDbTable::Query}{wxdbtablequery} returns true, the database was able to successfully complete the requested query using the provided criteria. This does not mean that there are any rows in the result set, it just mean that the query was successful. @@ -740,7 +720,7 @@ set into the bound memory variables. After \helpref{wxDbTable::Query}{wxdbtableq has completed successfully, the default/current cursor is placed so it is pointing just before the first record in the result set. If the result set is empty (no rows matched the criteria), then any calls to -retrieve data from the result set will return FALSE. +retrieve data from the result set will return false. \begin{verbatim} wxString msg; @@ -762,7 +742,7 @@ in the result set. When \helpref{wxDbTable::GetNext}{wxdbtablegetnext} is called and there are 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. +wxDbTable::GetXxxxx() functions) will return false. {\bf Close the table} @@ -832,7 +812,7 @@ this example it was stored in "DbConnectInf.Henv") have been closed, then it is safe to release the environment handle: \begin{verbatim} - DbConnectInf->FreeHenv()); + DbConnectInf->FreeHenv(); \end{verbatim} Or, if the long form of the constructor was used and the constructor was allowed @@ -894,7 +874,7 @@ functionality as the driver can emulate. \begin{itemize}\itemsep=0pt \item Does not support the SQL\_TIMESTAMP structure \item Supports only one cursor and one connect (apparently? with Microsoft driver only?) -\item Does not automatically create the primary index if the 'keyField' param of SetColDef is TRUE. The user must create ALL indexes from their program with calls to \helpref{wxDbTable::CreateIndex}{wxdbtablecreateindex} +\item Does not automatically create the primary index if the 'keyField' param of SetColDef is true. The user must create ALL indexes from their program with calls to \helpref{wxDbTable::CreateIndex}{wxdbtablecreateindex} \item Table names can only be 8 characters long \item Column names can only be 10 characters long \item Currently cannot CREATE a dBase table - bug or limitation of the drivers used?? @@ -916,7 +896,7 @@ functionality as the driver can emulate. {\it mySQL} \begin{itemize}\itemsep=0pt \item If a column is part of the Primary Key, the column cannot be NULL. -\item Cannot support selecting for update [\helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate}]. Always returns FALSE. +\item Cannot support selecting for update [\helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate}]. Always returns false. \item Columns that are part of primary or secondary keys must be defined as being NOT NULL when they are created. Some code is added in \helpref{wxDbTable::CreateIndex}{wxdbtablecreateindex} to try to adjust the column definition if it is not defined correctly, but it is experimental (as of wxWindows v2.2.1) \item Does not support sub-queries in SQL statements \end{itemize} @@ -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 @@ -958,7 +938,7 @@ wxDbTable *table = NULL; // The data table to access wxChar FirstName[50+1]; // buffer for data from column "FIRST_NAME" wxChar LastName[50+1]; // buffer for data from column "LAST_NAME" -bool errorOccured = FALSE; +bool errorOccured = false; const wxChar tableName[] = "CONTACTS"; const UWORD numTableColumns = 2; // Number of bound columns @@ -990,9 +970,9 @@ table = new wxDbTable(db, tableName, numTableColumns, "", // returned back to the client. // table->SetColDefs(0, "FIRST_NAME", DB_DATA_TYPE_VARCHAR, FirstName, - SQL_C_CHAR, sizeof(name), TRUE, TRUE); + SQL_C_CHAR, sizeof(name), true, true); table->SetColDefs(1, "LAST_NAME", DB_DATA_TYPE_VARCHAR, LastName, - SQL_C_CHAR, sizeof(LastName), TRUE, TRUE); + SQL_C_CHAR, sizeof(LastName), true, true); // Open the table for access table->Open(); @@ -1015,7 +995,7 @@ if (!table->Query()) { wxMessageBox("Error on Query()","ERROR!", wxOK | wxICON_EXCLAMATION); - errorOccured = TRUE; + errorOccured = true; } wxString msg; @@ -1058,194 +1038,7 @@ delete 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.