Some doc corrections

[wxWidgets.git] / docs / latex / wx / tdb.tex

diff --git a/docs/latex/wx/tdb.tex b/docs/latex/wx/tdb.tex
index 4ff6da4cc9afa2dfa5907164486e9a6d570a4b0f..7a2d7be7fca25e3b0450bd8a4e6185a384c58b4f 100644 (file)
--- a/docs/latex/wx/tdb.tex
+++ b/docs/latex/wx/tdb.tex
@@ -1,29 +1,9 @@
 \section{Database classes overview}\label{odbcoverview}
 
 \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 
 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}
 
 
 \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 
 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}
 
 
 {\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.
 
 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 
 
 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();
 
 // 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 
 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);
 }
 
     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
 // 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)
 {
 if (table)
 {

-    delete table;
-    table = NULL;
+    wxDelete(table);

 }
 
 // If we have a valid wxDb instance, then free the connection
 }
 
 // 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
 
 // Release the environment handle that was created
 // for use with the ODBC datasource connections

-delete DbConnectInf;
+wxDelete(DbConnectInf);

 
 \end{verbatim}
 
 
 \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.
 
 The following is a very brief description of some common SQL commands, with
 examples.