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 standard wxWindows classes for database
+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
directory indicating where the data file is stored, is required for Text and
dBase drivers for ODBC.
-The wxWindows data structure "wxDbConnectInf" exists for holding all of these
+The wxWindows data class wxDbConnectInf exists for holding all of these
values, plus some others that may be desired.
-\begin{verbatim}
- wxDbConnectInf
- HENV Henv;
- char Dsn[SQL_MAX_DSN_LENGTH+1] // DataSource Name
- char Uid[20+1] // User ID
- char AuthStr[20+1] // Authorization (password)
-
- // Optional needed for some databases like dBase, FoxPro and TEXT files
- char defaultDir[wxDB_PATH_MAX] // Directory that db file resides in
-
- char description[SQL_MAX_DSN_LENGTH+1];
- char fileType[SQL_MAX_DSN_LENGTH+1];
-\end{verbatim}
-
The 'Henv' member is the environment handle used to access memory for use by the
ODBC driver. Use of this member is described below in the "Getting a Connection
to the Datasource" section.
\begin{verbatim}
wxDbConnectInf DbConnectInf;
- wxStrcpy(DbConnectInf.Dsn, "Your DSN");
- wxStrcpy(DbConnectInf.Uid, "YourUserName");
- wxStrcpy(DbConnectInf.AuthStr, "YourUserPassword");
- wxStrcpy(DbConnectInf.defaultDir, "");
+ DbConnectInf.SetDsn,"MyDSN");
+ DbConnectInf.SetUserID,"MyUserName");
+ DbConnectInf.SetPassword("MyPassword");
+ DbConnectInf.SetDefaultDir("");
\end{verbatim}
To allocate an environment handle for the ODBC connection to use, the
-standard SQLAllocEnv() function is used.
+wxDbConnectInf class has a datasource independent method for creating
+the necessary handle:
\begin{verbatim}
- if (SQLAllocEnv(&DbConnectInf.Henv) != SQL_SUCCESS)
+ if (DbConnectInf.AllocHenv())
{
wxMessageBox("Unable to allocate an ODBC environment handle",
"DB CONNECTION ERROR", wxOK | wxICON_EXCLAMATION);
}
\end{verbatim}
-When the SQLAllocEnv() function is called successfully, a value of
-SQL_SUCCESS will be returned. Anything other return value is a failure
-to create the handle, and the handle will be undefined.
+When the wxDbConnectInf::AllocHenv() function is called successfully, a
+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
+long form of the constructor for wxDbConnectInf.
+
+\begin{verbatim}
+ wxDbConnectInf *DbConnectInf;
+
+ DbConnectInf = new wxDbConnectInf(NULL, "MyDSN", "MyUserName",
+ "MyPassword", "");
+\end{verbatim}
-Once the members of the wxDbConnectInf structure are initialized, you are
-now ready to connect to the datasource.
+This shorthand form of initializing the constructor passes a NULL for the SQL
+environment handle, telling the constructor to allocate a handle during
+construction. This handle is also managed for the life of wxDbConnectInf
+instance, and is freed automatically upon destruction of the instance.
+
+Once the wxDbConnectInf instance is initialized, you are ready to
+connect to the datasource.
To manually create datasource connections, you must create a wxDb
instance, and then open it.
\begin{verbatim}
- wxDb *db = new wxDb(DbConnectInf.Henv);
- opened = db->Open(DbConnectInf.Dsn, DbConnectInf.Uid,
- DbConnectInf.AuthStr);
+ wxDb *db = new wxDb(DbConnectInf->GetHenv());
+
+ opened = db->Open(DbConnectInf);
\end{verbatim}
-The first line does the house keeping needed to initialize everything all
+The first line does the house keeping needed to initialize all
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}.
type wxDbConnectInf:
\begin{verbatim}
- db = wxDbGetConnection(&DbConnectInf);
+ db = wxDbGetConnection(DbConnectInf);
\end{verbatim}
The wxDb pointer that is returned is both initialized and opened. If
class is to create a wxDbTable instance.
\begin{verbatim}
- table = new wxDbTable(db, tableName, numTableColumns, 0,
- !wxDB_QUERY_ONLY, NULL);
+ table = new wxDbTable(db, tableName, numTableColumns, "",
+ !wxDB_QUERY_ONLY, "");
\end{verbatim}
When you create the instance, you indicate the previously established
it is safe to release the environment handle:
\begin{verbatim}
- SQLFreeEnv(DbConnectInf.Henv);
+ DbConnectInf->FreeHenv());
+\end{verbatim}
+Or, if the long form of the constructor was used and the constructor was allowed
+to allocate its own SQL environment handle, leaving scope or destruction of the
+wxDbConnectInf will free the handle automatically.
+
+\begin{verbatim}
+ delete DbConnectInf;
\end{verbatim}
\normalbox{Remember to never release this environment handle if there are any
-connections still using the handle.
-}
+connections still using the handle.}
\subsection{wxODBC - Known Issues}\label{wxodbcknownissues}
code and to make it more easily readable.
\begin{verbatim}
-struct wxDbConnectInf DbConnectInf;
+wxDbConnectInf *DbConnectInf = NULL;
wxDb *db = NULL; // The database connection
wxDbTable *table = NULL; // The data table to access
-char FirstName[50+1]; // buffer for data from column "FIRST_NAME"
-char LastName[50+1]; // buffer for data from column "LAST_NAME"
+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;
-const char tableName[] = "CONTACTS";
-const int numTableColumns = 2; // Number of bound columns
+const wxChar tableName[] = "CONTACTS";
+const UWORD numTableColumns = 2; // Number of bound columns
FirstName[0] = 0;
LastName[0] = 0;
-// Initialize the ODBC Environment for database operations
-// and store the handle in 'DbConnectInf.Henv'
-if (SQLAllocEnv(&DbConnectInf.Henv) != SQL_SUCCESS)
+DbConnectInf = new wxDbConnectInf(NULL,"MyDSN","MyUserName", "MyPassword");
+
+if (!DbConnectInf || !DbConnectInf->GetHenv())
{
-wxMessageBox("Unable to allocate an ODBC environment handle",
- "DB CONNECTION ERROR", wxOK | wxICON_EXCLAMATION);
-return;
+ wxMessageBox("Unable to allocate an ODBC environment handle",
+ "DB CONNECTION ERROR", wxOK | wxICON_EXCLAMATION);
+ return;
}
-wxStrcpy(DbConnectInf.Dsn, "Your DSN");
-wxStrcpy(DbConnectInf.Uid, "YourUserName");
-wxStrcpy(DbConnectInf.AuthStr, "YourUserPassword");
-wxStrcpy(DbConnectInf.defaultDir, "");
-
// Get a database connection from the cached connections
-db = wxDbGetConnection(&DbConnectInf);
+db = wxDbGetConnection(DbConnectInf);
// Create the table connection
-table = new wxDbTable(db, tableName, numTableColumns, 0,
- !wxDB_QUERY_ONLY, NULL);
+table = new wxDbTable(db, tableName, numTableColumns, "",
+ !wxDB_QUERY_ONLY, "");
//
// Bind the columns that you wish to retrieve. Note that there must be
// Release the environment handle that was created
// for use with the ODBC datasource connections
-SQLFreeEnv(DbConnectInf.Henv);
+delete DbConnectInf;
\end{verbatim}
-
-\subsection{wxDatabase ODBC class overview [DEPRECATED]}\label{wxodbcoverview}
+\subsection{wxDatabase ODBC class overview [DEPRECATED]}\label{oldwxodbcoverview}
Classes: \helpref{wxDatabase}{wxdatabase}, \helpref{wxRecordSet}{wxrecordset}, \helpref{wxQueryCol}{wxquerycol},
\rtfsp\helpref{wxQueryField}{wxqueryfield}
projects / wxWidgets.git / blobdiff