db.tex

来自「Wxpython Implemented on Windows CE, Sou」· TEX 代码 · 共 1,509 行 · 第 1/5 页

Searches the list of cached database connections connection for one matching
the passed in wxDb instance.  If found, that cached connection is freed.

Freeing a connection means that it is marked as available (free) in the
cache of connections, so that a call to \helpref{wxDbGetConnection}{wxdbfunctions}
is able to return a pointer to the wxDb instance for use.  Freeing a
connection does NOT close the connection, it only makes the connection
available again.


\func{wxDb *}{wxDbGetConnection}{\param{wxDbConnectInf *}{pDbConfig},
\param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}

\wxheading{Remarks}

This function is used to request a "new" wxDb instance for use by the program.
The wxDb instance returned is also opened (see \helpref{wxDb::Open}{wxdbopen}).

This function (along with wxDbFreeConnection() and wxDbCloseConnection())
maintain a cache of wxDb instances for user/re-use by a program.  When a
program needs a wxDb instance, it may call this function to obtain a wxDb
instance.  If there is a wxDb instance in the cache that is currently unused
that matches the connection requirements specified in {\it'pDbConfig'} then
that cached connection is marked as no longer being free, and a pointer to
the wxDb instance is returned.

If there are no connections available in the cache that meet the requirements
given in {\it'pDbConfig'}, then a new wxDb instance is created to connect
to the datasource specified in {\it'pDbConfig'} using the userID and password
given in {\it'pDbConfig'}.

NOTE: The caching routine also uses the \helpref{wxDb::Open}{wxdbopen}
connection datatype copying code.  If the call to wxDbGetConnection()
requests a connection to a datasource, and there is not one available in the
cache, a new connection is created.  But when the connection is opened,
instead of polling the datasource over again for its datatypes, if a
connection to the same datasource (using the same userID/password) has already
been done previously, the new connection skips querying the datasource for
its datatypes, and uses the same datatypes determined previously by the
other connection(s) for that same datasource.  This cuts down greatly on
network traffic, database load, and connection creation time.

When the program is done using a connection created through a call to
wxDbGetConnection(), the program should call wxDbFreeConnection() to release
the wxDb instance back to the cache.  DO NOT DELETE THE wxDb INSTANCE!
Deleting the wxDb instance returned can cause a crash/memory corruption
later in the program when the cache is cleaned up.

When exiting the program, call wxDbCloseConnections() to close all the
cached connections created by calls to wxDbGetConnection().


\func{const wxChar *}{wxDbLogExtendedErrorMsg}{\param{const wxChar *}{userText}, \param{wxDb *}{pDb}, \param{wxChar *}{ErrFile}, \param{int }{ErrLine}}

Writes a message to the wxLog window (stdout usually) when an internal
error situation occurs.

\func{bool}{wxDbSqlLog}{\param{wxDbSqlLogState }{state}, \param{const wxString \&}{filename = SQL\_LOG\_FILENAME}}

\wxheading{Remarks}

This function sets the sql log state for all open wxDb objects

\func{bool}{wxDbGetDataSource}{\param{HENV }{henv}, \param{wxChar *}{Dsn}, \param{SWORD }{DsnMax}, \param{wxChar *}{DsDesc}, \param{SWORD }{DsDescMax}, \param{UWORD }{direction = SQL\_FETCH\_NEXT}}

\wxheading{Remarks}

This routine queries the ODBC driver manager for a list of available
datasources.  Repeatedly call this function to obtain all the datasources
available through the ODBC driver manager on the current workstation.

\begin{verbatim}
    wxArrayString strArray;

    while (wxDbGetDataSource(DbConnectInf.GetHenv(), Dsn, SQL_MAX_DSN_LENGTH+1, DsDesc, 255))
        strArray.Add(Dsn);
\end{verbatim}

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

\membersection{wxDb::wxDb}\label{wxdbctor}

\func{}{wxDb}{\void}

Default constructor.

\func{}{wxDb}{\param{const HENV \&}{aHenv}, \param{bool }{FwdOnlyCursors=(bool)wxODBC\_FWD\_ONLY\_CURSORS}}

Constructor, used to create an ODBC connection to a datasource.

\wxheading{Parameters}

\docparam{aHenv}{Environment handle used for this connection.  See
\helpref{wxDConnectInf::AllocHenv}{wxdbconnectinfallochenv}}

\docparam{FwdOnlyCursors}{Will cursors created for use with this datasource
connection only allow forward scrolling cursors.}

\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}
   wxDbConnectInf ConnectInf;
   ....Set values for member variables of ConnectInf here

   wxDb sampleDB(ConnectInf.GetHenv());
   if (!sampleDB.Open(ConnectInf.GetDsn(), ConnectInf.GetUserID(),
	                   ConnectInf.GetPassword()))
   {
      // Error opening datasource
   }
\end{verbatim}

\wxheading{See also}

\helpref{wxDbGetConnection}{wxdbfunctions}

\membersection{wxDb::Catalog}\label{wxdbcatalog}

\func{bool}{Catalog}{\param{wxChar *}{ userID}, \param{const wxString \&}{fileName =
SQL\_CATALOG\_FILENAME}}

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

\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}{{\it OPTIONAL}.  Name of the text file to create and write
the DB catalog to.  Default is SQL\_CATALOG\_FILENAME.}

\wxheading{Return value}

Returns true if the catalog request was successful, or false if there was some
reason that the catalog could not be generated.

\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}\label{wxdbclose}

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

Closes the database connection.

\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 datasource.  There are actually
four steps involved in doing this as illustrated in the example.

Any wxDbTable instances which use this connection must be deleted before
closing the database connection.

\wxheading{Example}

\begin{verbatim}
   // Commit any open transactions on the datasource
   sampleDB.CommitTrans();

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

   // Close the wxDb connection when finished with it
   sampleDB.Close();
\end{verbatim}


\membersection{wxDb::CommitTrans}\label{wxdbcommittrans}

\func{bool}{CommitTrans}{\void}

Permanently "commits" changes (insertions/deletions/updates) to the database.

\wxheading{Return value}

Returns true if the commit was successful, or false if the commit failed.

\wxheading{Remarks}

Transactions begin implicitly as soon as you make a change to the database
with an insert/update/delete, or any other direct SQL command that performs
one of these operations against the datasource.
At any time thereafter, to save the changes to disk permanently, "commit"
them by calling this function.

Calling this member function commits ALL open transactions on this ODBC
connection.  For example, if three different wxDbTable instances used the
same connection to the datasource, committing changes made on one of those
wxDbTable instances commits any pending transactions on all three wxDbTable
instances.

Until a call to wxDb::CommitTrans() is made, no other user or cursor is able
to see any changes made to the row(s) that have been inserted/modified/deleted.


\wxheading{Special Note : {\it Cursors} }

\normalbox{It is important to understand that different database/ODBC driver
combinations handle transactions differently.  One thing in particular that
you must pay attention to is cursors, in regard to transactions.  Cursors are
what allow you to scroll through records forward and backward and to
manipulate records as you scroll through them.  When you issue a query, a
cursor is created behind the scenes.  The cursor keeps track of the query and
keeps track of the current record pointer.  After you commit or rollback a
transaction, the cursor may be closed automatically.  This is database
dependent, and with some databases this behavior can be controlled through
management functions.  This means you would need to requery the datasource
before you can perform any additional work using this cursor.  This is only
necessary however if the datasource closes the cursor after a commit or
rollback.  Use the
\helpref{wxDbTable::IsCursorClosedOnCommit}{wxdbtableiscursorclosedoncommit}
member function to determine the datasource's transaction behavior.  Note, in
many situations it is very inefficient to assume the cursor is closed and
always requery.  This could put a significant, unnecessary load on datasources
that leave the cursors open after a transaction.}


\membersection{wxDb::CreateView}\label{wxdbcreateviews}

\func{bool}{CreateView}{\param{const wxString \&}{ viewName},
\param{const wxString \&}{ colList}, \param{const wxString \&}{pSqlStmt}}

Creates a SQL VIEW of one or more tables in a single datasource.  Note that
this function will only work against databases which support views (currently
only Oracle as of November 21 2000).

\wxheading{Parameters}

\docparam{viewName}{The name of the view.  e.g. PARTS\_V}

\docparam{colList}{{\it OPTIONAL} Pass in a comma delimited list of column
names if you wish to explicitly name each column in the result set.  If not
desired, pass in an empty string and the column names from the associated
table(s) will be used.}

\docparam{pSqlStmt}{Pointer to the select statement portion of the CREATE
VIEW statement.  Must be a complete, valid SQL SELECT statement.}

\wxheading{Remarks}

A 'view' is a logical table that derives columns from one or more other
tables or views.  Once the view is created, it can be queried exactly like
any other table in the database.

NOTE: Views are not available with all datasources.  Oracle is one example
of a datasource which does support views.

\wxheading{Example}

\begin{verbatim}
   // Incomplete code sample
   db.CreateView("PARTS_SD1", "PN, PD, QTY",
                 "SELECT PART_NUM, PART_DESC, QTY_ON_HAND * 1.1 FROM PARTS \
                  WHERE STORAGE_DEVICE = 1");

   // PARTS_SD1 can now be queried just as if it were a data table.
   // e.g. SELECT PN, PD, QTY FROM PARTS_SD1
\end{verbatim}


\membersection{wxDb::Dbms}\label{wxdbdbms}

\func{wxDBMS }{Dbms}{\void}

\wxheading{Remarks}

The return value will be of the enumerated type wxDBMS.  This enumerated
type contains a list of all the currently tested and supported databases.

Additional databases may work with these classes, but the databases
returned by this function have been tested and confirmed to work with
these ODBC classes.

Possible values returned by this function can be viewed in the
\helpref{Enumerated types}{wxdbenumeratedtypes} section of wxDb.

There are known issues with conformance to the ODBC standards with several
datasources supported by the wxWidgets ODBC classes.  Please see the overview
for specific details on which datasource have which issues.

\wxheading{Return value}