Added first stab at GetBoundingRect for generic tree control

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

\section{\class{wxDB}}\label{wxdb}

A wxDB instance is a connection to an ODBC data source which may
be opened, closed, and re-opened an unlimited number of times.  A
database connection allows function to be performed directly on the
data source, as well as allowing access to any tables/views defined in
the data source to which the user has sufficient privileges.

\wxheading{Include files}

<wx/version.h>
<wx/iodbc.h>
<wx/isqlext.h>
<wx/db.h>

\wxheading{Remarks}

By default, cursor directional scrolling is defined by wxODBC_FWD_ONLY_CURSORS
when the wxWindows library is built.  This behavior can be overridden when 
an instance of a wxDB is created (see \helpref{wxDB constructor}{wxdbconstr}

\wxheading{See also}

\helpref{wxTable}{wxtable}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDB::wxDB}\label{wxdbconstr}

\func{}{wxDB}{\void}

Default constructor.

\func{}{wxDB}{\param{HENV\& }{aHenv}}

Constructor, used to create an ODBC connection to a data source.

\wxheading{Parameters}

\docparam{aHenv}{Environment handle defined in iODBC}

\wxheading{Remarks}

This is the constructor for the wxDB class.  The wxDB object must
be created and opened before any database activity can occur.

\wxheading{Example}
\begin{verbatim}
   HENV Db;
   ....Set values for member variables here

   wxDB sampleDB(Db.Henv);
   if (!sampleDB.Open(Db.Dsn, Db.Uid, Db.AuthStr))
   {
      // Error opening data source
   }
\end{verbatim}


\membersection{wxDB::Catalog}

\func{bool}{Catalog}{\param{char *}{ userID}, \param{char *}{fileName = SQL_CATALOG_FILENAME}}

\wxheading{Parameters}

\docparam{userID}{Database user name to use in accessing the database.  All tables to which this user has rights will be evaluated in the catalog.}

\docparam{fileName}{OPTIONAL argument.  Name of the text file to create and write the DB catalog to.}

\wxheading{Remarks}

Allows a data "dictionary" of the data source to be created, dumping pertinent information about all data tables to which the user specified in userID has access. 

\wxheading{Example}
\begin{verbatim}
============== ============== ================ ========= =======
TABLE NAME     COLUMN NAME    DATA TYPE        PRECISION  LENGTH
============== ============== ================ ========= =======
EMPLOYEE       RECID          (0008)NUMBER            15       8
EMPLOYEE       USER_ID        (0012)VARCHAR2          13      13
EMPLOYEE       FULL_NAME      (0012)VARCHAR2          26      26
EMPLOYEE       PASSWORD       (0012)VARCHAR2          26      26
EMPLOYEE       START_DATE     (0011)DATE              19      16
\end{verbatim}


\membersection{wxDB::Close}

\func{void}{Close}{\void}

\wxheading{Remarks}

At the end of your program, when you have finished all of your database work, you must close the ODBC connection to the data source.  There are actually four steps involved in doing this as illustrated in the example.

\wxheading{Example}
\begin{verbatim}
   // Commit any open transactions on the data source
   sampleDB.CommitTrans();

   // Delete any remaining wxTable objects allocated with new
   delete parts;

   // Close the wxDB connection when finished with it
   sampleDB.Close();

   // Free Environment Handle that ODBC uses
   if (SQLFreeEnv(Db.Henv) != SQL_SUCCESS)
   {
      // Error freeing environment handle
   }
\end{verbatim}