db.tex

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

The return value will indicate which of the supported datasources is
currently connected to by this connection.  In the event that the
datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.


\membersection{wxDb::DispAllErrors}\label{wxdbdispallerrors}

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

Used to log all database errors that occurred as a result of an executed
database command.  This logging is automatic and also includes debug logging
when compiled in debug mode via \helpref{wxLogDebug}{wxlogdebug}.  If logging
is turned on via \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, then an
entry is also logged to the defined log file.

\wxheading{Parameters}

\docparam{aHenv}{Handle to the ODBC environment.}

\docparam{aHdbc}{Handle to the ODBC connection.  Pass this in if the ODBC
function call that erred required a hdbc or hstmt argument.}

\docparam{aHstmt}{Handle to the ODBC statement being executed against.  Pass
this in if the ODBC function call that failed required a hstmt argument.}

\wxheading{Remarks}

This member function will log all of the ODBC error messages for the last
ODBC function call that was made.  This function is normally used internally
within the ODBC class library, but can be used programmatically after calling
ODBC functions directly (i.e. SQLFreeEnv()).

\wxheading{Return value}

The function always returns false, so a call to this function can be made
in the return statement of a code block in the event of a failure to
perform an action (see the example below).

\wxheading{See also}

\helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, wxDbSqlLog

\wxheading{Example}

\begin{verbatim}
   if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
      // Display all ODBC errors for this stmt
      return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
\end{verbatim}

\membersection{wxDb::DispNextError}\label{wxdbdispnexterror}

\func{void}{DispNextError}{\void}

\wxheading{Remarks}

This function is normally used internally within the ODBC class library.
It could be used programmatically after calling ODBC functions directly.  This
function works in conjunction with \helpref{wxDb::GetNextError}{wxdbgetnexterror} when errors (or
sometimes informational messages)  returned from ODBC need to be analyzed
rather than simply displaying them as an error.  GetNextError() retrieves
the next ODBC error from the ODBC error queue.  The wxDb member variables
"sqlState", "nativeError" and "errorMsg" could then be evaluated.  To
display the error retrieved, DispNextError() could then be called.
The combination of GetNextError() and DispNextError() can be used to
iteratively step through the errors returned from ODBC evaluating each
one in context and displaying the ones you choose.

\wxheading{Example}

\begin{verbatim}
   // Drop the table before attempting to create it
   sprintf(sqlStmt, "DROP TABLE %s", tableName);
   // Execute the drop table statement
   if (SQLExecDirect(hstmt,(UCHAR FAR *)sqlStmt,SQL_NTS) != SQL_SUCCESS)
   {
      // Check for sqlState = S0002, "Table or view not found".
      // Ignore this error, bomb out on any other error.
      pDb->GetNextError(henv, hdbc, hstmt);
      if (wxStrcmp(pDb->sqlState, "S0002"))
      {
         pDb->DispNextError();   // Displayed error retrieved
         pDb->DispAllErrors(henv, hdbc, hstmt); // Display all other errors, if any
         pDb->RollbackTrans();   // Rollback the transaction
         CloseCursor();          // Close the cursor
         return(false);          // Return Failure
      }
   }
\end{verbatim}


\membersection{wxDb::DropView}\label{wxdbdropview}

\func{bool}{DropView}{\param{const wxString \&}{viewName}}

Drops the data table view named in 'viewName'.

\wxheading{Parameters}

\docparam{viewName}{Name of the view to be dropped.}

\wxheading{Remarks}

If the view does not exist, this function will return true.  Note that views are not supported with all datasources.

\membersection{wxDb::ExecSql}\label{wxdbexecsql}

\func{bool}{ExecSql}{\param{const wxString \&}{pSqlStmt}}

\func{bool}{ExecSql}{\param{const wxString \&}{pSqlStmt}, \param{wxDbColInf **}{columns}, \param{short \&}{numcols}}

Allows a native SQL command to be executed directly against the datasource.  In addition to being able to run any standard SQL command, use of this function allows a user to (potentially) utilize features specific to the datasource they are connected to that may not be available through ODBC.  The ODBC driver will pass the specified command directly to the datasource.

To get column amount and column names or other information about returned columns, pass {\it 'columns'} and {\it 'numcols'} parameters to the function also.

\wxheading{Parameters}

\docparam{pSqlStmt}{Pointer to the SQL statement to be executed.}

\docparam{columns}{On success, this function will set this pointer to point to array of \helpref{wxDbColInf}{wxdbcolinf} objects, holding information about columns returned by the query. You need to call delete[] for the pointer you pass here after you don't use it anymore to prevent memory leak.}

\docparam{numcols}{Reference to variable where amount of objects in {\it 'columns'}-parameter will be set.}

\wxheading{Remarks}

This member extends the wxDb class and allows you to build and execute ANY VALID
SQL statement against the datasource.  This allows you to extend the class
library by being able to issue any SQL statement that the datasource is capable
of processing.

\wxheading{See also}

\helpref{wxDb::GetData}{wxdbgetdata}, \helpref{wxDb::GetNext}{wxdbgetnext}

\membersection{wxDb::FwdOnlyCursors}\label{wxdbfwdonlycursors}

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

Older form (pre-2.3/2.4 of wxWidgets) of the
\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors}.  This method is
provided for backward compatibility only.  The method
\helpref{wxDb::IsFwdOnlyCursors}{wxdbisfwdonlycursors} should be
used in place of this method.


\func{wxDbInf *}{GetCatalog}{\param{const wxChar *}{userID}}

\membersection{wxDb::GetCatalog}\label{wxdbgetcatalog}

\func{wxDbInf *}{GetCatalog}{\param{const wxChar *}{userID}}

Returns a \helpref{wxDbInf}{wxdbinf} pointer that points to the catalog
(datasource) name, schema, number of tables accessible to the current user,
and a wxDbTableInf pointer to all data pertaining to all tables in the users
catalog.

\wxheading{Parameters}

\docparam{userID}{Owner/Schema 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.  {\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}

The returned catalog will only contain catalog entries for tables to which the user specified in 'userID' has sufficient privileges.  If no user is specified (NULL passed in), a catalog pertaining to all tables in the datasource accessible to the connected user (permissions apply) via this connection will be returned.

\membersection{wxDb::GetColumnCount}\label{wxdbgetcolumncount}

\func{int }{GetColumnCount}{\param{const wxString \&}{tableName}, \param{const wxChar *}{userID}}

\wxheading{Parameters}

\docparam{tableName}{The table name you wish to obtain column information about.}

\docparam{userID}{Name of the user that owns the table(s) (also referred to as schema).
Required for some datasources for situations where there may be multiple tables with the
same name in the datasource, but owned by different users. {\it userID } is
evaluated in the following manner:}

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

\wxheading{Return value}

Returns a count of how many columns are in the specified table.  If an error
occurs retrieving the number of columns, this function will return a -1.

\membersection{wxDb::GetColumns}\label{wxdbgetcolumns}

\func{wxDbColInf *}{GetColumns}{\param{const wxString \&}{tableName}, \param{UWORD *}{numCols}, \param{const wxChar *}{userID=NULL}}

\func{wxDbColInf *}{GetColumns}{\param{wxChar *}{tableName[]}, \param{const wxChar *}{userID}}

\wxheading{Parameters}

\docparam{tableName}{The table name you wish to obtain column information about.}
\docparam{numCols}{Pointer to a UWORD which will hold a count of the number of columns returned by this function}
\docparam{tableName[]}{An array of pointers to table names you wish to obtain column information about.  The last element of this array must be a NULL string.}
\docparam{userID}{Name of the user that owns the table(s) (also referred to as schema).  Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. {\it userID} is evaluated in the following manner:}

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

\wxheading{Return value}

This function returns a pointer to an array of \helpref{wxDbColInf}{wxdbcolinf}
structures, allowing you to obtain information regarding the columns of the
named table(s).  If no columns were found, or an error occurred, this pointer
will be NULL.

THE CALLING FUNCTION IS RESPONSIBLE FOR DELETING THE {\it wxDbColInf} MEMORY WHEN IT IS
FINISHED WITH IT.

\normalbox{ALL column bindings associated with this wxDb instance are unbound
by this function, including those used by any wxDbTable instances that use
this wxDb instance.  This function should use its own wxDb instance
to avoid undesired unbinding of columns.}

\wxheading{See also}

\helpref{wxDbColInf}{wxdbcolinf}

\wxheading{Example}

\begin{verbatim}
   wxChar *tableList[] = {"PARTS", 0};
   wxDbColInf *colInf = pDb->GetColumns(tableList);
   if (colInf)
   {
      // Use the column inf
      .......
      // Destroy the memory
      delete [] colInf;
   }
\end{verbatim}

\membersection{wxDb::GetData}\label{wxdbgetdata}

\func{bool}{GetData}{\param{UWORD}{ colNumber}, \param{SWORD}{ cType},
\param{PTR}{ pData}, \param{SDWORD}{ maxLen}, \param{SDWORD FAR *}{ cbReturned} }

Used to retrieve result set data without binding column values to memory
variables (i.e. not using a wxDbTable instance to access table data).

\wxheading{Parameters}

\docparam{colNumber}{Ordinal number of the desired column in the result set to be
returned.}
\docparam{cType}{The C data type that is to be returned.  See a partial list
in \helpref{wxDbTable::SetColDefs}{wxdbtablesetcoldefs}}
\docparam{pData}{Memory buffer which will hold the data returned by the call
to this function.}
\docparam{maxLen}{Maximum size of the buffer {\it 'pData'} in characters.
NOTE: Not UNICODE safe.  If this is a numeric field, a value of 0 may be
passed for this parameter, as the API knows the size of the expected return
value.}
\docparam{cbReturned}{Pointer to the buffer containing the length of the
actual data returned.  If this value comes back as SQL\_NULL\_DATA, then the
\helpref{wxDb::GetData}{wxdbgetdata} call has failed.}

\wxheading{See also}

\helpref{wxDb::GetNext}{wxdbgetnext}, \helpref{wxDb::ExecSql}{wxdbexecsql}

\wxheading{Example}

\begin{verbatim}
    SDWORD cb;
    ULONG reqQty;
    wxString sqlStmt;
    sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
                 PART_RECID = 1450 AND REQUIRED_QTY > PICKED_QTY";

    // Perform the query
    if (!pDb->ExecSql(sqlStmt.c_str()))
    {
        // ERROR
        return(0);
    }

    // Request the first row of the result set
    if (!pDb->GetNext())
    {
        // ERROR
        return(0);
    }

    // Read column #1 of the row returned by the call to ::GetNext()
    // and return the value in 'reqQty'
    if (!pDb->GetData(1, SQL_C_ULONG, &reqQty, 0, &cb))
    {
        // ERROR