db.tex

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

    // Check for a NULL result
    if (cb == SQL_NULL_DATA)
        return(0);
\end{verbatim}

\wxheading{Remarks}

When requesting multiple columns to be returned from the result set (for example, the SQL query
requested 3 columns be returned), the calls to this function must request the columns in ordinal
sequence (1,2,3 or 1,3 or 2,3).

\membersection{wxDb::GetDatabaseName}\label{wxdbgetdatabasename}

\func{const wxChar *}{GetDatabaseName}{\void}

Returns the name of the database engine.

\membersection{wxDb::GetDatasourceName}\label{wxdbgetdatasourcename}

\func{const wxString \&}{GetDatasourceName}{\void}

Returns the ODBC datasource name.

\membersection{wxDb::GetHDBC}\label{wxdbgethdbc}

\func{HDBC}{GetHDBC}{\void}

Returns the ODBC handle to the database connection.

\membersection{wxDb::GetHENV}\label{wxdbgethenv}

\func{HENV}{GetHENV}{\void}

Returns the ODBC environment handle.

\membersection{wxDb::GetHSTMT}\label{wxdbgethstmt}

\func{HSTMT}{GetHSTMT}{\void}

Returns the ODBC statement handle associated with this database connection.

\membersection{wxDb::GetKeyFields}\label{wxdbgetkeyfields}

\func{int }{GetKeyFields}{\param{const wxString \&}{tableName}, \param{wxDbColInf *}{colInf}, \param{UWORD }{numColumns}}

Used to determine which columns are members of primary or non-primary indexes on the specified table.  If a column is a member of a foreign key for some other table, that information is detected also.

This function is primarily for use by the \helpref{wxDb::GetColumns}{wxdbgetcolumns} function, but may be called if desired from the client application.

\wxheading{Parameters}

\docparam{tableName}{Name of the table for which the columns will be evaluated as to their inclusion in any indexes.}
\docparam{colInf}{Data structure containing the column definitions (obtained with \helpref{wxDb::GetColumns}{wxdbgetcolumns}).  This function populates the PkCol, PkTableName, and FkTableName members of the colInf structure.}
\docparam{numColumns}{Number of columns defined in the instance of colInf.}

\wxheading{Return value}

Currently always returns true.

\wxheading{See also}

\helpref{wxDbColInf}{wxdbcolinf}, \helpref{wxDb::GetColumns}{wxdbgetcolumns}

\membersection{wxDb::GetNext}\label{wxdbgetnext}

\func{bool}{GetNext}{\void}

Called after executing a query, this function requests the next row
in the result set after the current position of the cursor.

\wxheading{See also}

\helpref{wxDb::ExecSql}{wxdbexecsql}, \helpref{wxDb::GetData}{wxdbgetdata}

\membersection{wxDb::GetNextError}\label{wxdbgetnexterror}

\func{bool}{GetNextError}{\param{HENV}{ aHenv},
\param{HDBC}{ aHdbc = SQL\_NULL\_HDBC}, \param{HSTMT}{ aHstmt = SQL\_NULL\_HSTMT}}

\wxheading{Parameters}

\docparam{aHenv}{A handle to the ODBC environment.}
\docparam{aHdbc}{{\it OPTIONAL.}  A handle to the ODBC connection.  Pass this
in if the ODBC function call that failed required a hdbc or hstmt argument.}
\docparam{AHstmt}{{\it OPTIONAL.}A handle to the ODBC statement being executed
against.  Pass this in if the ODBC function call that failed requires a
hstmt argument.}

\wxheading{Example}

\begin{verbatim}
   if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
   {
      return(db.GetNextError(db.henv, db.hdbc, hstmt));
   }
\end{verbatim}

\wxheading{See also}

\helpref{wxDb::DispNextError}{wxdbdispnexterror},
\helpref{wxDb::DispAllErrors}{wxdbdispallerrors}


\membersection{wxDb::GetPassword}\label{wxdbgetpassword}

\func{const wxString \&}{GetPassword}{\void}

Returns the password used to establish this connection to the datasource.


\membersection{wxDb::GetTableCount}\label{wxdbgettablecount}

\func{int }{GetTableCount}{\void}

Returns the number of wxDbTable() instances currently using this datasource
connection.


\membersection{wxDb::GetUsername}\label{wxdbgetusername}

\func{const wxString \&}{GetUsername}{\void}

Returns the user name (uid) used to establish this connection to the
datasource.


\membersection{wxDb::Grant}\label{wxdbgrant}

\func{bool}{Grant}{\param{int }{privileges}, \param{const wxString \&}{tableName},
\param{const wxString \&}{userList = "PUBLIC"}}

Use this member function to GRANT privileges to users for accessing tables in
the datasource.

\wxheading{Parameters}

\docparam{privileges}{Use this argument to select which privileges you want to
grant.  Pass DB\_GRANT\_ALL to grant all privileges.  To grant individual
privileges pass one or more of the following OR'd together:}

\begin{verbatim}
         DB_GRANT_SELECT  = 1
         DB_GRANT_INSERT  = 2
         DB_GRANT_UPDATE  = 4
         DB_GRANT_DELETE  = 8
         DB_GRANT_ALL     = DB_GRANT_SELECT | DB_GRANT_INSERT |
                            DB_GRANT_UPDATE | DB_GRANT_DELETE
\end{verbatim}

\docparam{tableName}{The name of the table you wish to grant privileges on.}
\docparam{userList}{{\it OPTIONAL.}  A comma delimited list of users to grant the privileges to.  If this argument is not passed in, the privileges will be given to the general PUBLIC.}

\wxheading{Remarks}

Some databases require user names to be specified in all capital letters (i.e. Oracle).  This function does not automatically capitalize the user names passed in the comma-separated list.  This is the responsibility of the calling routine.

The currently logged in user must have sufficient grantor privileges for this
function to be able to successfully grant the indicated privileges.

\wxheading{Example}

\begin{verbatim}
   db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
\end{verbatim}

\membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}

\func{bool}{IsFwdOnlyCursors}{\void}

This setting indicates whether this database connection was created
as being capable of using only forward scrolling cursors.

This function does NOT indicate if the ODBC driver or datasource supports
backward scrolling cursors.  There is no standard way of detecting if the
driver or datasource can support backward scrolling cursors.

If a wxDb instance was created as being capable of only forward scrolling
cursors, then even if the datasource and ODBC driver support backward
scrolling cursors, tables using this database connection would only be able
to use forward scrolling cursors.

The default setting of whether a wxDb connection to a database allows
forward-only or also backward scrolling cursors is defined in setup.h by the
value of wxODBC\_FWD\_ONLY\_CURSORS.  This default setting can be overridden
when the wxDb connection is initially created (see
\helpref{wxDb constructor}{wxdbctor} and \helpref{wxDbGetConnection}{wxdbfunctions}).

\wxheading{Return value}

Returns true if this datasource connection is defined as using only forward
scrolling cursors, or false if the connection is defined as being allowed to
use backward scrolling cursors and their associated functions (see note above).

\wxheading{Remarks}

Added as of wxWidgets v2.4 release, this function is a renamed version of
wxDb::FwdOnlyCursors() to match the normal wxWidgets naming conventions for
class member functions.

This function is not available in versions prior to v2.4.  You should
use \helpref{wxDb::FwdOnlyCursors}{wxdbfwdonlycursors} for wxWidgets
versions prior to 2.4.

\wxheading{See also}

\helpref{wxDb constructor}{wxdbctor}, \helpref{wxDbGetConnection}{wxdbfunctions}

\membersection{wxDb::IsOpen}\label{wxdbisopen}

\func{bool}{IsOpen}{\void}

Indicates whether the database connection to the datasource is currently
opened.

\wxheading{Remarks}

This function may indicate that the database connection is open, even if
the call to \helpref{wxDb::Open}{wxdbopen} may have failed to fully
initialize the connection correctly.  The connection to the database
{\it is} open and can be used via the direct SQL commands, if this
function returns true.  Other functions which depend on the
\helpref{wxDb::Open}{wxdbopen} to have completed correctly may not function
as expected.  The return result from \helpref{wxDb::Open}{wxdbopen} is the
only way to know if complete initialization of this wxDb connection was
successful or not.  See \helpref{wxDb::Open}{wxdbopen} for more details on
partial failures to open a connection instance.

\membersection{wxDb::LogError}\label{wxdblogerror}

\func{void}{LogError}{\param{const wxString \&}{errMsg} \param{const wxString \&}{SQLState=""}}

\docparam{errMsg}{Free-form text to display describing the error/text to be logged.}
\docparam{SQLState}{{\it OPTIONAL.}  Native SQL state error.  Default is 0.}

\wxheading{Remarks}

Calling this function will enter a log message in the error list maintained
for the database connection.  This log message is free form and can be
anything the programmer wants to enter in the error list.

If SQL logging is turned on, the call to this function will also log the
text into the SQL log file.

\wxheading{See also}

\helpref{wxDb::WriteSqlLog}{wxdbwritesqllog}

\membersection{wxDb::ModifyColumn}\label{wxdbmodifycolumn}

\func{void}{ModifyColumn}{\param{const wxString \&}{tableName} \param{const wxString \&}{ColumnName}
\param{int }{dataType} \param{ULONG }{columnLength=0} \param{const wxString \&}{optionalParam=""}}

Used to change certain properties of a column such as the length, or whether a column
allows NULLs or not.

\docparam{tableName}{Name of the table that the column to be modified is in.}
\docparam{columnName}{Name of the column to be modified.  NOTE: Name of column cannot
be changed with this function.}
\docparam{dataType}{Any one of DB\_DATA\_TYPE\_VARCHAR, DB\_DATA\_TYPE\_INTEGER,
DB\_DATA\_TYPE\_FLOAT, DB\_DATA\_TYPE\_DATE.}
\docparam{columnLength}{New size of the column.  Valid only for DB\_DATA\_TYPE\_VARCHAR
dataType fields.  Default is 0.}
\docparam{optionalParam}{Default is "".}

\wxheading{Remarks}

Cannot be used to modify the precision of a numeric column, therefore 'columnLength'
is ignored unless the dataType is DB\_DATA\_TYPE\_VARCHAR.

Some datasources do not allow certain properties of a column to be changed if any rows
currently have data stored in that column.  Those datasources that do allow columns
to be changed with data in the rows many handle truncation and/or expansion in
different ways.  Please refer to the reference material for the datasource being
used for behavioral descriptions.

\wxheading{Example}

\begin{verbatim}
    ok = pDb->ModifyColumn("CONTACTS", "ADDRESS2",
                            DB_, colDefs[j].SzDataObj,
                            wxT("NOT NULL"));
\end{verbatim}


\membersection{wxDb::Open}\label{wxdbopen}

\func{bool}{Open}{\param{const wxString \&}{Dsn}, \param{const wxString \&}{Uid},
\param{const wxString \&}{AuthStr}, \param{bool }{failOnDataTypeUnsupported}}

\func{bool}{Open}{\param{const wxString \&}{inConnectStr}, 
\param{bool }{failOnDataTypeUnsupported}}

\func{bool}{Open}{\param{wxDbConnectInf *}{dbConnectInf}, 
\param{bool }{failOnDataTypeUnsupported}}

\func{bool}{Open}{\param{wxDb *}{copyDb}}

Opens a connection to the datasource, sets certain behaviors of the datasource
to confirm to the accepted behaviors (e.g. cursor position maintained on
commits), and queries the datasource for its representations of the basic
datatypes to determine the form in which the data going to/from columns in
the data tables are to be handled.

The second form of this function, which accepts a "wxDb *" as a parameter,
can be used to avoid the overhead (execution time, database load, network
traffic) which are needed to determine the data types and representations
of data that are necessary for cross-datasource support by these classes.