db.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

Normally the first form of the wxDb::Open() function will open the connection
and then send a series of queries to the datasource asking it for its
representation of data types, and all the features it supports.  If one
connection to the datasource has already been made previously, the information
gathered when that connection was created can just be copied to any new
connections to the same datasource by passing a pointer to the first
connection in as a parameter to the wxDb::Open() function.  Note that this
new connection created from the first connections information will use the
same Dsn/Uid/AuthStr as the first connection used.

\wxheading{Parameters}

\docparam{Dsn}{datasource name.  The name of the ODBC datasource as
assigned when the datasource is initially set up through the ODBC data
source manager.}
\docparam{Uid}{User ID.  The name (ID) of the user you wish to connect as
to the datasource.  The user name (ID) determines what objects you
have access to in the datasource and what datasource privileges you have.
Privileges include being able to create new objects, update objects, delete
objects and so on.  Users and privileges are normally administered by the
database administrator.}
\docparam{AuthStr}{The password associated with the Uid.}
\docparam{failOnDataTypeUnsupporte}{As part of connecting to a database, the 
wxDb::Open() function will query the database to find out the native types 
that it supports.  With some databases, some data types may not be supported,
or not sufficiently supported, for use with the wxODBC classes.  Normally
a program should fail in this case, so as not to try to use a data type
that is not supported.  This parameter allows the programmer to override the
failure if they wish and continue on using the connection.}
\docparam{dbConnectInf}{Contains a DSN, Uid, Password, or a connection string 
to be used in opening a new connection to the database.  If a connection
string is present, then the connection string will be used.  If there is no 
connection string present, then the DSN, Uid, and Password are used.}
\docparam{inConnectStr}{A valid ODBC connection string used to connect to a 
database}
\docparam{copyDb}{Already completely configured and opened datasource 
connection from which all Dsn, Uid, AuthStr, connection string, and data 
typing information is to be copied from for use by this datasource 
connection.  If 'copyDb' used a connection string to create its connection 
originally, then the connection being made by this call to wxDb::Open() will 
use that same connection string.}

\wxheading{Remarks}

After a wxDb instance is created, it must then be opened.  When opening a
datasource, there must be three pieces of information passed.  The data
source name, user name (ID) and the password for the user.  No database
activity on the datasource can be performed until the connection is opened.
This is normally done at program startup and the datasource remains
open for the duration of the program/module run.

It is possible to have connections to multiple datasources open at the same
time to support distributed database connections by having separate instances
of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.

If this function returns a value of false, it does not necessarily mean that
the connection to the datasource was not opened.  It may mean that some
portion of the initialization of the connection failed (such as a datatype not
being able to be determined how the datasource represents it).  To determine
if the connection to the database failed, use the \helpref{wxDb::IsOpen}{wxdbisopen}
function after receiving a false result back from this function to determine if
the connection was opened or not.  If this function returns false, but \helpref{wxDb::IsOpen}{wxdbisopen}
returns true, then direct SQL commands may be passed to the database
connection and can be successfully executed, but use of the datatypes (such as
by a wxDbTable instance) that are normally determined during open will not be
possible.

\normalbox{The {\it Dsn}, {\it Uid}, and {\it AuthStr} string pointers that are passed in
are copied.  NOT the strings themselves, only the pointers.  The calling routine
must maintain the memory for these three strings for the life of the wxDb instance.}

\wxheading{Example}

\begin{verbatim}
   wxDb sampleDB(DbConnectInf.GetHenv());
   if (!sampleDB.Open("Oracle 7.1 HP/UX", "gtasker", "myPassword"))
   {
      if (sampleDb.IsOpen())
      {
        // Connection is open, but the initialization of
        // datatypes and parameter settings failed
      }
      else
      {
        // Error opening datasource
      }
   }
\end{verbatim}

\membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}

\func{bool}{RollbackTrans}{\void}

Function to "undo" changes made to the database.  After an insert/update/delete, the operation may be "undone" by issuing this command any time before a \helpref{wxDb::CommitTrans}{wxdbcommittrans} is called on the database connection.

\wxheading{Remarks}

Transactions begin implicitly as soon as you make a change to the database.  The
transaction continues until either a commit or rollback is executed.  Calling
wxDb::RollbackTrans() will result in ALL changes done using this database
connection that have not already been committed to be "undone" back to the last
commit/rollback that was successfully executed.

\normalbox{Calling this member function rolls back ALL open (uncommitted)
transactions on this ODBC connection, including all wxDbTable instances that
use this connection.}

\wxheading{See also}

\helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors

\membersection{wxDb::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}

\func{void}{SetDebugErrorMessages}{\param{bool }{state}}

\docparam{state}{Either true (debug messages are logged) or false (debug
messages are not logged).}

\wxheading{Remarks}

Turns on/off debug error messages from the ODBC class library.  When
this function is passed true, errors are reported to the user/logged automatically
in a text or pop-up dialog when an ODBC error occurs.  When passed false,
errors are silently handled.

When compiled in release mode (FINAL=1), this setting has no affect.

\wxheading{See also}

\helpref{wxDb constructor}{wxdbctor}

\membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}

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

\wxheading{Parameters}

\docparam{state}{Either sqlLogOFF or sqlLogON (see \helpref{enum wxDbSqlLogState}{wxdbcolfor}). Turns logging of SQL commands sent to the datasource OFF or ON.}
\docparam{filename}{{\it OPTIONAL}.  Name of the file to which the log text is to be written.  Default is SQL\_LOG\_FILENAME.}
\docparam{append}{{\it OPTIONAL}. Whether the file is appended to or overwritten.  Default is false.}

\wxheading{Remarks}

When called with {\it sqlLogON}, all commands sent to the datasource engine are logged to the file specified by {\it filename}.  Logging is done by embedded \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} calls in the database member functions, or may be manually logged by adding calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} in your own source code.

When called with {\it sqlLogOFF}, the logging file is closed, and any calls to \helpref{wxDb::WriteSqlLog}{wxdbwritesqllog} are ignored.

\membersection{wxDb::SQLColumnName}\label{wxdbsqlcolumnname}

\func{const wxString}{SQLColumnName}{\param{const wxChar *}{ colName}}

Returns the column name in a form ready for use in SQL statements.
In most cases, the column name is returned verbatim.  But some databases
(e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which
must be specially quoted.  For example, if the datasource allows spaces
in the column name, the returned string will have the correct enclosing
marks around the name to allow it to be properly included in a SQL statement
for the DBMS that is currently connected to with this connection.

\wxheading{Parameters}

\docparam{colName}{Native name of the column in the table that is to be
evaluated to determine if any special quoting marks needed to be added to it
before including the column name in a SQL statement}

\wxheading{See also}

\helpref{wxDb::SQLTableName}{wxdbsqltablename}

\membersection{wxDb::SQLTableName}\label{wxdbsqltablename}

\func{const wxString}{SQLTableName}{\param{const wxChar *}{ tableName}}

Returns the table name in a form ready for use in SQL statements.
In most cases, the table name is returned verbatim.  But some databases
(e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which
must be specially quoted.  For example, if the datasource allows spaces
in the table name, the returned string will have the correct enclosing
marks around the name to allow it to be properly included in a SQL statement
for the data source that is currently connected to with this connection.

\wxheading{Parameters}

\docparam{tableName}{Native name of the table that is to be evaluated to
determine if any special quoting marks needed to be added to it
before including the table name in a SQL statement}

\wxheading{See also}

\helpref{wxDb::SQLColumnName}{wxdbsqlcolumnname}

\membersection{wxDb::TableExists}\label{wxdbtableexists}

\func{bool}{TableExists}{\param{const wxString \&}{tableName}, \param{const wxChar *}{userID=NULL}, \param{const wxString \&}{path=""}}

Checks the ODBC datasource for the existence of a table.  If a {\it userID}
is specified, then the table must be accessible by that user (user must have
at least minimal privileges to the table).

\wxheading{Parameters}

\docparam{tableName}{Name of the table to check for the existence of.}
\docparam{userID}{Owner of the table (also referred to as schema).  Specify a userID when the datasource you are connected
to allows multiple unique tables with the same name to be owned by different users.  {\it userID}
is evaluated as follows:}

\begin{verbatim}
         userID == NULL  ... UserID is ignored (DEFAULT)
         userID == ""    ... UserID set equal to 'this->uid'
         userID != ""    ... UserID set equal to 'userID'
\end{verbatim}

\wxheading{Remarks}

{\it tableName} may refer to a table, view, alias or synonym.

This function does not indicate whether or not the user has privileges to query or perform other functions on the table.  Use the \helpref{wxDb::TablePrivileges}{wxdbtableprivileges} to determine if the user has sufficient privileges or not.

\wxheading{See also}

\helpref{wxDb::TablePrivileges}{wxdbtableprivileges}

\membersection{wxDb::TablePrivileges}\label{wxdbtableprivileges}

\func{bool}{TablePrivileges}{\param{const wxString \&}{tableName}, \param{const wxString \&}{priv},
\param{const wxChar *}{userID=NULL}, \param{const wxChar *}{schema=NULL},
\param{const wxString \&}{path=""}}

Checks the ODBC datasource for the existence of a table.  If a {\it userID}
is specified, then the table must be accessible by that user (user must have
at least minimal privileges to the table).

\wxheading{Parameters}

\docparam{tableName}{Name of the table on which to check privileges.
{\it tableName} may refer to a table, view, alias or synonym.}
\docparam{priv}{The table privilege being evaluated. May be one of the
following (or a datasource specific privilege):}

\begin{verbatim}
    SELECT      : The connected user is permitted to retrieve data for
                  one or more columns of the table.

    INSERT      : The connected user is permitted to insert new rows
                  containing data for one or more columns into the
                  table.

    UPDATE      : The connected user is permitted to update the data in
                  one or more columns of the table.

    DELETE      : The connected user is permitted to delete rows of
                  data from the table.

    REFERENCES  : Is the connected user permitted to refer to one or
                  more columns of the table within a constraint (for
                  example, a unique, referential, or table check
                  constraint).
\end{verbatim}

\docparam{userID}{{\it OPTIONAL.}  User for which to determine if the privilege
specified to be checked is granted or not.  Default is "".
{\it userID} is evaluated as follows:}

\begin{verbatim}
         userID == NULL  ... NOT ALLOWED!
         userID == ""    ... UserID set equal to 'this->uid'
         userID != ""    ... UserID set equal to 'userID'
\end{verbatim}

\docparam{schema}{{\it OPTIONAL.}  Owner of the table.  Specify a userID when the datasource
you are connected to allows multiple unique tables with the same name to be
owned by different users.  Specifying the table owner makes determination of the
users privileges MUCH faster.  Default is NULL.  {\it userID} is
evaluated as follows:}

\begin{verbatim}
         schema == NULL  ... Any owner (DEFAULT)
         schema == ""    ... Owned by 'this->uid'
         schema != ""    ... Owned by userID specified in 'schema'
\end{verbatim}

\docparam{path}{{\it OPTIONAL.}  Path to the table.  Default is "".
Currently unused.}

\wxheading{Remarks}

The scope of privilege allowed to the connected user by a given table
privilege is datasource dependent.

For example, the privilege UPDATE might allow the connected user to update
all columns in a table on one datasource, but only those columns for
which the grantor (the user that granted the connected user) has the UPDATE
privilege on another datasource.

Looking up a user's privileges to a table can be time consuming depending on the
datasource and ODBC driver.  This time can be minimized by passing a {\it schema}
as a parameter.  With some datasources/drivers, the difference can be several
seconds of time difference.


\membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}

\func{int }{TranslateSqlState}{\param{const wxString \&}{SQLState}}

Converts an ODBC sqlstate to an internal error code.

\wxheading{Parameters}

\docparam{SQLState}{State to be converted