docs/latex/wx/db.tex

   1 \section{\class{wxDB}}\label{wxdb}
   2
   3 A wxDB instance is a connection to an ODBC data source which may
   4 be opened, closed, and re-opened an unlimited number of times.  A
   5 database connection allows function to be performed directly on the
   6 data source, as well as allowing access to any tables/views defined in
   7 the data source to which the user has sufficient privileges.
   8
   9 \wxheading{Include files}
  10
  11 <wx/version.h>
  12 <wx/iodbc.h>
  13 <wx/isqlext.h>
  14 <wx/db.h>
  15
  16 \wxheading{Remarks}
  17
  18 By default, cursor directional scrolling is defined by wxODBC_FWD_ONLY_CURSORS
  19 when the wxWindows library is built.  This behavior can be overridden when
  20 an instance of a wxDB is created (see \helpref{wxDB constructor}{wxdbconstr}
  21
  22 \wxheading{See also}
  23
  24 \helpref{wxTable}{wxtable}
  25
  26 \latexignore{\rtfignore{\wxheading{Members}}}
  27
  28 \membersection{wxDB::wxDB}\label{wxdbconstr}
  29
  30 \func{}{wxDB}{\void}
  31
  32 Default constructor.
  33
  34 \func{}{wxDB}{\param{HENV\& }{aHenv}}
  35
  36 Constructor, used to create an ODBC connection to a data source.
  37
  38 \wxheading{Parameters}
  39
  40 \docparam{aHenv}{Environment handle defined in iODBC}
  41
  42 \wxheading{Remarks}
  43
  44 This is the constructor for the wxDB class.  The wxDB object must
  45 be created and opened before any database activity can occur.
  46
  47 \wxheading{Example}
  48 \begin{verbatim}
  49    HENV Db;
  50    ....Set values for member variables here
  51
  52    wxDB sampleDB(Db.Henv);
  53    if (!sampleDB.Open(Db.Dsn, Db.Uid, Db.AuthStr))
  54    {
  55       // Error opening data source
  56    }
  57 \end{verbatim}
  58
  59
  60 \membersection{wxDB::Catalog}
  61
  62 \func{bool}{Catalog}{\param{char *}{ userID}, \param{char *}{fileName = SQL_CATALOG_FILENAME}}
  63
  64 \wxheading{Parameters}
  65
  66 \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.}
  67
  68 \docparam{fileName}{OPTIONAL argument.  Name of the text file to create and write the DB catalog to.}
  69
  70 \wxheading{Remarks}
  71
  72 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.
  73
  74 \wxheading{Example}
  75 \begin{verbatim}
  76 ============== ============== ================ ========= =======
  77 TABLE NAME     COLUMN NAME    DATA TYPE        PRECISION  LENGTH
  78 ============== ============== ================ ========= =======
  79 EMPLOYEE       RECID          (0008)NUMBER            15       8
  80 EMPLOYEE       USER_ID        (0012)VARCHAR2          13      13
  81 EMPLOYEE       FULL_NAME      (0012)VARCHAR2          26      26
  82 EMPLOYEE       PASSWORD       (0012)VARCHAR2          26      26
  83 EMPLOYEE       START_DATE     (0011)DATE              19      16
  84 \end{verbatim}
  85
  86
  87 \membersection{wxDB::Close}
  88
  89 \func{void}{Close}{\void}
  90
  91 \wxheading{Remarks}
  92
  93 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.
  94
  95 \wxheading{Example}
  96 \begin{verbatim}
  97    // Commit any open transactions on the data source
  98    sampleDB.CommitTrans();
  99
 100    // Delete any remaining wxTable objects allocated with new
 101    delete parts;
 102
 103    // Close the wxDB connection when finished with it
 104    sampleDB.Close();
 105
 106    // Free Environment Handle that ODBC uses
 107    if (SQLFreeEnv(Db.Henv) != SQL_SUCCESS)
 108    {
 109       // Error freeing environment handle
 110    }
 111 \end{verbatim}
 112