cheng/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
4c6224f523
wxWidgets/docs/latex/wx/db.tex
Bryan Petty 3ca6a5f046 second merge of the 2.2 branch (RL) 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@7973 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
2000-08-08 06:11:51 +00:00

1066 lines
42 KiB
TeX
Raw Blame History

\section{\class{wxDb}}\label{wxdb}
A wxDb instance is a connection to an ODBC data source which may
be opened, closed, and re-opened an unlimited number of times. A
database connection allows function to be performed directly on the
data source, as well as allowing access to any tables/views defined in
the data source to which the user has sufficient privileges.
\wxheading{Include files}
<wx/version.h>
<wx/iodbc.h>
<wx/isqlext.h>
<wx/db.h>
\latexignore{\rtfignore{\wxheading{Members}}}
\wxheading{Enumerated types}
\label{wxdbenumsqllogstate}\docparam{enum {\bf wxDbSqlLogState}}{sqlLogOFF, sqlLogON}
{\it enum {\bf wxDBMS}}
These are the databases currently tested and working with these ODBC classes.
A call to \helpref{wxDb::Dbms}{wxdbdbms} will return one of these enumerated values listed below.
\begin{verbatim}
dbmsUNIDENTIFIED,
dbmsORACLE,
dbmsSYBASE_ASA, // Adaptive Server Anywhere
dbmsSYBASE_ASE, // Adaptive Server Enterprise
dbmsMS_SQL_SERVER,
dbmsMY_SQL,
dbmsPOSTGRES,
dbmsACCESS,
dbmsDBASE,
dbmsINFORMIX
\end{verbatim}
See the remarks in \helpref{wxDb::Dbms}{wxdbdbms} for exceptions/issues with
each of these database engines.
\wxheading{Public member variables}
\docparam{SWORD {\bf wxDb::cbErrorMsg}}{This member variable is populated as a result of
calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}. Contains the count of bytes in the wxDb::errorMsg string.}
\label{wxdbdbstatus}\docparam{int {\bf wxDb::DB_STATUS}}{The last ODBC error that occured on this data connection. Possible codes are:}
\begin{verbatim}
DB_ERR_GENERAL_WARNING // SqlState = '01000'
DB_ERR_DISCONNECT_ERROR // SqlState = '01002'
DB_ERR_DATA_TRUNCATED // SqlState = '01004'
DB_ERR_PRIV_NOT_REVOKED // SqlState = '01006'
DB_ERR_INVALID_CONN_STR_ATTR // SqlState = '01S00'
DB_ERR_ERROR_IN_ROW // SqlState = '01S01'
DB_ERR_OPTION_VALUE_CHANGED // SqlState = '01S02'
DB_ERR_NO_ROWS_UPD_OR_DEL // SqlState = '01S03'
DB_ERR_MULTI_ROWS_UPD_OR_DEL // SqlState = '01S04'
DB_ERR_WRONG_NO_OF_PARAMS // SqlState = '07001'
DB_ERR_DATA_TYPE_ATTR_VIOL // SqlState = '07006'
DB_ERR_UNABLE_TO_CONNECT // SqlState = '08001'
DB_ERR_CONNECTION_IN_USE // SqlState = '08002'
DB_ERR_CONNECTION_NOT_OPEN // SqlState = '08003'
DB_ERR_REJECTED_CONNECTION // SqlState = '08004'
DB_ERR_CONN_FAIL_IN_TRANS // SqlState = '08007'
DB_ERR_COMM_LINK_FAILURE // SqlState = '08S01'
DB_ERR_INSERT_VALUE_LIST_MISMATCH // SqlState = '21S01'
DB_ERR_DERIVED_TABLE_MISMATCH // SqlState = '21S02'
DB_ERR_STRING_RIGHT_TRUNC // SqlState = '22001'
DB_ERR_NUMERIC_VALUE_OUT_OF_RNG // SqlState = '22003'
DB_ERR_ERROR_IN_ASSIGNMENT // SqlState = '22005'
DB_ERR_DATETIME_FLD_OVERFLOW // SqlState = '22008'
DB_ERR_DIVIDE_BY_ZERO // SqlState = '22012'
DB_ERR_STR_DATA_LENGTH_MISMATCH // SqlState = '22026'
DB_ERR_INTEGRITY_CONSTRAINT_VIOL // SqlState = '23000'
DB_ERR_INVALID_CURSOR_STATE // SqlState = '24000'
DB_ERR_INVALID_TRANS_STATE // SqlState = '25000'
DB_ERR_INVALID_AUTH_SPEC // SqlState = '28000'
DB_ERR_INVALID_CURSOR_NAME // SqlState = '34000'
DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL // SqlState = '37000'
DB_ERR_DUPLICATE_CURSOR_NAME // SqlState = '3C000'
DB_ERR_SERIALIZATION_FAILURE // SqlState = '40001'
DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL2 // SqlState = '42000'
DB_ERR_OPERATION_ABORTED // SqlState = '70100'
DB_ERR_UNSUPPORTED_FUNCTION // SqlState = 'IM001'
DB_ERR_NO_DATA_SOURCE // SqlState = 'IM002'
DB_ERR_DRIVER_LOAD_ERROR // SqlState = 'IM003'
DB_ERR_SQLALLOCENV_FAILED // SqlState = 'IM004'
DB_ERR_SQLALLOCCONNECT_FAILED // SqlState = 'IM005'
DB_ERR_SQLSETCONNECTOPTION_FAILED // SqlState = 'IM006'
DB_ERR_NO_DATA_SOURCE_DLG_PROHIB // SqlState = 'IM007'
DB_ERR_DIALOG_FAILED // SqlState = 'IM008'
DB_ERR_UNABLE_TO_LOAD_TRANSLATION_DLL // SqlState = 'IM009'
DB_ERR_DATA_SOURCE_NAME_TOO_LONG // SqlState = 'IM010'
DB_ERR_DRIVER_NAME_TOO_LONG // SqlState = 'IM011'
DB_ERR_DRIVER_KEYWORD_SYNTAX_ERROR // SqlState = 'IM012'
DB_ERR_TRACE_FILE_ERROR // SqlState = 'IM013'
DB_ERR_TABLE_OR_VIEW_ALREADY_EXISTS // SqlState = 'S0001'
DB_ERR_TABLE_NOT_FOUND // SqlState = 'S0002'
DB_ERR_INDEX_ALREADY_EXISTS // SqlState = 'S0011'
DB_ERR_INDEX_NOT_FOUND // SqlState = 'S0012'
DB_ERR_COLUMN_ALREADY_EXISTS // SqlState = 'S0021'
DB_ERR_COLUMN_NOT_FOUND // SqlState = 'S0022'
DB_ERR_NO_DEFAULT_FOR_COLUMN // SqlState = 'S0023'
DB_ERR_GENERAL_ERROR // SqlState = 'S1000'
DB_ERR_MEMORY_ALLOCATION_FAILURE // SqlState = 'S1001'
DB_ERR_INVALID_COLUMN_NUMBER // SqlState = 'S1002'
DB_ERR_PROGRAM_TYPE_OUT_OF_RANGE // SqlState = 'S1003'
DB_ERR_SQL_DATA_TYPE_OUT_OF_RANGE // SqlState = 'S1004'
DB_ERR_OPERATION_CANCELLED // SqlState = 'S1008'
DB_ERR_INVALID_ARGUMENT_VALUE // SqlState = 'S1009'
DB_ERR_FUNCTION_SEQUENCE_ERROR // SqlState = 'S1010'
DB_ERR_OPERATION_INVALID_AT_THIS_TIME // SqlState = 'S1011'
DB_ERR_INVALID_TRANS_OPERATION_CODE // SqlState = 'S1012'
DB_ERR_NO_CURSOR_NAME_AVAIL // SqlState = 'S1015'
DB_ERR_INVALID_STR_OR_BUF_LEN // SqlState = 'S1090'
DB_ERR_DESCRIPTOR_TYPE_OUT_OF_RANGE // SqlState = 'S1091'
DB_ERR_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1092'
DB_ERR_INVALID_PARAM_NO // SqlState = 'S1093'
DB_ERR_INVALID_SCALE_VALUE // SqlState = 'S1094'
DB_ERR_FUNCTION_TYPE_OUT_OF_RANGE // SqlState = 'S1095'
DB_ERR_INF_TYPE_OUT_OF_RANGE // SqlState = 'S1096'
DB_ERR_COLUMN_TYPE_OUT_OF_RANGE // SqlState = 'S1097'
DB_ERR_SCOPE_TYPE_OUT_OF_RANGE // SqlState = 'S1098'
DB_ERR_NULLABLE_TYPE_OUT_OF_RANGE // SqlState = 'S1099'
DB_ERR_UNIQUENESS_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1100'
DB_ERR_ACCURACY_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1101'
DB_ERR_DIRECTION_OPTION_OUT_OF_RANGE // SqlState = 'S1103'
DB_ERR_INVALID_PRECISION_VALUE // SqlState = 'S1104'
DB_ERR_INVALID_PARAM_TYPE // SqlState = 'S1105'
DB_ERR_FETCH_TYPE_OUT_OF_RANGE // SqlState = 'S1106'
DB_ERR_ROW_VALUE_OUT_OF_RANGE // SqlState = 'S1107'
DB_ERR_CONCURRENCY_OPTION_OUT_OF_RANGE // SqlState = 'S1108'
DB_ERR_INVALID_CURSOR_POSITION // SqlState = 'S1109'
DB_ERR_INVALID_DRIVER_COMPLETION // SqlState = 'S1110'
DB_ERR_INVALID_BOOKMARK_VALUE // SqlState = 'S1111'
DB_ERR_DRIVER_NOT_CAPABLE // SqlState = 'S1C00'
DB_ERR_TIMEOUT_EXPIRED // SqlState = 'S1T00'
\end{verbatim}
\docparam{struct {\bf wxDb::dbInf}}{This structure is internal to the wxDb class and contains
details of the ODBC datasource that the current instance of the wxDb is connected to
in its members. When the data source is opened, all of the information contained in
the dbInf structure is queried from the data source. This information is used almost
exclusively within the ODBC class library. Where there is a need for this information
outside of the class library a member function such as wxTable::IsCursorClosedOnCommit()
has been added for ease of use.}
\begin{verbatim}
char dbmsName[40] - Name of the dbms product
char dbmsVer[64] - Version # of the dbms product
char driverName[40] - Driver name
char odbcVer[60] - ODBC version of the driver
char drvMgrOdbcVer[60] - ODBC version of the driver manager
char driverVer[60] - Driver version
char serverName[80] - Server Name, typically a connect string
char databaseName[128] - Database filename
char outerJoins[2] - Does datasource support outer joins
char procedureSupport[2] - Does datasource support stored procedures
UWORD maxConnections - Maximum # of connections datasource supports
UWORD maxStmts - Maximum # of HSTMTs per HDBC
UWORD apiConfLvl - ODBC API conformance level
UWORD cliConfLvl - Is datasource SAG compliant
UWORD sqlConfLvl - SQL conformance level
UWORD cursorCommitBehavior - How cursors are affected on db commit
UWORD cursorRollbackBehavior - How cursors are affected on db rollback
UWORD supportNotNullClause - Does datasource support NOT NULL clause
char supportIEF[2] - Integrity Enhancement Facility (Ref. Integrity)
UDWORD txnIsolation - Transaction isolation level supported by driver
UDWORD txnIsolationOptions - Transaction isolation level options available
UDWORD fetchDirections - Fetch directions supported
UDWORD lockTypes - Lock types supported in SQLSetPos
UDWORD posOperations - Position operations supported in SQLSetPos
UDWORD posStmts - Position statements supported
UDWORD scrollConcurrency - Scrollable cursor concurrency options supported
UDWORD scrollOptions - Scrollable cursor options supported
UDWORD staticSensitivity - Can additions/deletions/updates be detected
UWORD txnCapable - Indicates if datasource supports transactions
UDWORD loginTimeout - Number seconds to wait for a login request
\end{verbatim}
\docparam{char {\bf wxDb::errorList}[DB_MAX_ERROR_HISTORY][DB_MAX_ERROR_MSG_LEN]}{The last n ODBC errors that have occured on this database connection.}
\docparam{char {\bf wxDb::errorMsg}[SQL_MAX_MESSAGE_LENGTH]}{This member variable is populated as a result of calling \helpref{wxDb::GetNextError}{wxdbgetnexterror}. It contains the ODBC error message text.}
\docparam{SDWORD {\bf wxDb::nativeError}}{Set by wxDb::DispAllErrors, wxDb::GetNextError, and wxDb::DispNextError. It contains the datasource-specific error code returned by the datasource to the ODBC driver. Used for reporting ODBC errors.}
\docparam{wxChar {\bf wxDb::sqlState}[20]}{Set by wxDb::TranslateSqlState(). Indicates the error state after a failed ODBC operation. Used for reporting ODBC errors.}
\docparam{unsigned int {\bf nTables}}{Number of wxDbTable objects connected to this wxDb instance. {\bf FOR INTERNAL USE ONLY} by wxDbTable!!!}
{\it wxDbSqlTypeInfo {\bf typeInfVarchar}}
{\it wxDbSqlTypeInfo {\bf typeInfInteger}}
{\it wxDbSqlTypeInfo {\bf typeInfFloat}}
{\it wxDbSqlTypeInfo {\bf typeInfDate}}
\begin{indented}{1cm}
The four wxDbSqlTypeInfo member variables listed above contain information about logical data types VARCHAR, INTEGER, FLOAT and DATE.
This information is obtained from the ODBC driver by use of the ::SQLGetTypeInfo() function. The key piece of information is the type name the datasource uses for each logical data type. e.g. VARCHAR; Oracle calls it VARCHAR2.
\end{indented}
\wxheading{Remarks}
Default cursor scrolling is defined by wxODBC_FWD_ONLY_CURSORS in setup.h
when the wxWindows library is built. This behavior can be overridden when
an instance of a wxDb is created (see \helpref{wxDb constructor}{wxdbconstr}
\wxheading{See also}
\helpref{wxDbColFor}{wxdbcolfor}, \helpref{wxDbColInf}{wxdbcolinf}, \helpref{wxDbTable}{wxdbtable}, \helpref{wxDbTableInf}{wxdbtableinf}, \helpref{wxDbInf}{wxdbinf}
\membersection{wxDb::wxDb}\label{wxdbconstr}
\func{}{wxDb}{\void}
Default constructor.
\func{}{wxDb}{\param{HENV\& }{aHenv}}
Constructor, used to create an ODBC connection to a data source.
\wxheading{Parameters}
\docparam{aHenv}{Environment handle defined in iODBC}
\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.Henv);
if (!sampleDB.Open(ConnectInf.Dsn, ConnectInf.Uid, ConnectInf.AuthStr))
{
// Error opening data source
}
\end{verbatim}
\membersection{wxDb::Catalog}\label{wxdbcatalog}
\func{bool}{Catalog}{\param{char *}{ userID}, \param{char *}{fileName = SQL_CATALOG_FILENAME}}
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.
\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}{OPTIONAL argument. Name of the text file to create and write the DB catalog to.}
\wxheading{Return value}
Returns TRUE if the catalog request was successful, of FALSE if there was some reason 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 data source. There are actually four steps involved in doing this as illustrated in the example.
Any wxTable instances which use this connection must be deleted before closing the database connection.
\wxheading{Example}
\begin{verbatim}
// Commit any open transactions on the data source
sampleDB.CommitTrans();
// Delete any remaining wxTable objects allocated with new
delete parts;
// Close the wxDb connection when finished with it
sampleDB.Close();
// Free Environment Handle that ODBC uses
if (SQLFreeEnv(Db.Henv) != SQL_SUCCESS)
{
// Error freeing environment handle
}
\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. At any time thereafter, you can save your work to the database ("Commit") or roll back all of your changes ("Rollback"). Calling this member function commits all open transactions on this ODBC connection.
\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 means you must
requery the data source before you can perform any additional work against the wxTable
object. This is only necessary however if the data source closes the cursor after a
commit or rollback. Use the wxTable::IsCursorClosedOnCommit() member function to
determine the data source's transaction behavior. Note, it would be very inefficient
to just assume the data source closes the cursor and always requery. This could put
a significant, unnecessary load on data sources that leave the cursors open after a
transaction.}
\membersection{wxDb::CreateView}\label{wxdbcreateviews}
\func{bool}{CreateView}{\param{char *}{ viewName}, \param{char *}{ colList}, \param{char *}{pSqlStmt}}
Creates a SQL VIEW.
\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.}
\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 datasouce which does support views.
\wxheading{Example}
\begin{verbatim}
// Incomplete code sample
db.CreateView("PARTS_SD1", "PN, PD, QTY",
"SELECT PART_NO, 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::DispAllErrors}\label{wxdbdispallerrors}
\func{bool}{DispAllErrors}{\param{HENV}{ aHenv}, {\param}{HDBC}{ aHdbc = SQL_NULL_HDBC}, {\param}{HSTMT}{ aHstmt = SQL_NULL_HSTMT}}
Logs all database errors that occurred as a result of the last executed database command. This logging 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}{A handle to the ODBC environment.}
\docparam{aHdbc}{A handle to the ODBC connection. Pass this in if the ODBC function call that
erred out required a hdbc or hstmt argument.}
\docparam{AHstmt}{A handle to the ODBC statement being executed against. Pass this in if the
ODBC function call that erred out required a hstmt argument.}
\wxheading{Remarks}
This member function will display all of the ODBC error messages for the last ODBC function call that was made. Normally used internally within the ODBC class library. Would be used externally if calling ODBC functions directly (i.e. SQLFreeEnv()).
\wxheading{See also}
\helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}, \helpref{wxDbSqlLog}{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 externally if 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 (strcmp(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 char *}{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 data soruces.
\membersection{wxDb::ExecSql}\label{wxdbexecsql}
\func{bool}{ExecSql}{\param{char *}{pSqlStmt}}
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.
\wxheading{Parameters}
\docparam{pSqlStmt}{Pointer to the SQL statement to be executed.}
\wxheading{Remarks}
This member extends the wxDb class and allows you to build and execute ANY VALID
SQL statement against the data source. This allows you to extend the class
library by being able to issue any SQL statement that the data source is capable
of processing.
\wxheading{See also}
\helpref{wxDb::GetData}{wxdbgetdata}, \helpref{wxDb::GetNext}{wxdbgetnext}
\membersection{wxDb::FwdOnlyCursors}\label{wxdbfwdonlycursors}
\func{bool}{FwdOnlyCursors}{\void}
Indicates whether this connection to the datasource only allows forward scrolling cursors or not. This state is set at connection creation time.
\wxheading{See also}
\helpref{wxDb::wxDb}{wxdbconstruct}, \helpref{wxDbGetConnection}{wxdbgetconnection}
\membersection{wxDb::GetCatalog}\label{wxdbgetcatalog}
\func{wxDbInf *}{GetCatalog}{\param{char *}{userID}}
Returns a wxDbInf pointer that points to the catalog(data source) 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 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 via this connection will be returned.
\membersection{wxDb::GetColumnCount}\label{wxdbgetcolumncount}
\func{int}{GetColumnCount}{\param{char *}{tableName}, \param{const char *}{userID}}
\wxheading{Parameters}
\docparam{tableName}{A table name you wish to obtain column information about.}
\docparam{userID}{Name of the user that owns the table(s). 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 the function will return a -1.
\membersection{wxDb::GetColumns}\label{wxdbgetcolumns}
\func{wxDbColInf *}{GetColumns}{\param{char *}{tableName}, \param{int *}{numCols}, \param{const char *}{userID=NULL}}
\func{wxDbColInf *}{GetColumns}{\param{char *}{tableName[]}, \param{const char *}{userID}}
\wxheading{Parameters}
\docparam{tableName}{A table name you wish to obtain column information about.}
\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{numCols}{A pointer to a integer which will hold a count of the number
of columns returned by this function}
\docparam{userID}{Name of the user that owns the table(s). 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 an array of wxDbColInf structures. This allows you to obtain
information regarding the columns of your table(s). If no columns were found, or
an error occured, this pointer will be zero (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. This function should use its own wxDb instance
to avoid undesired unbinding of columns.}
\wxheading{See also}
\helpref{wxDbColInf}{wxdbcolinf}
\wxheading{Example}
\begin{verbatim}
char *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}{ colNo}, \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{colNo}{Ordinal number of column in the result set to be returned.}
\docparam{cType}{The C data type that is to be returned.}
\docparam{pData}{Memory buffer which will hold the data returned by the call to this function.}
\docparam{maxLen}{Maximum size of the buffer that will hold the returned 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 GetData() 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 this row of the result set and store the value in 'reqQty'
if (!pDb->GetData(1, SQL_C_ULONG, &reqQty, 0, &cb))
{
// ERROR
return(0);
}
// 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 GetData must request the columns in ordinal
sequence (1,2,3 or 1,3 or 2,3).
\membersection{wxDb::GetDatabaseName}\label{wxdbgetdatabasename}
\func{char *}{GetDatabaseName}{\void}
Returns the name of the database engine.
\membersection{wxDb::GetDataSource}\label{wxdbgetdatasource}
\func{char *}{GetDataSource}{\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{char *}{tableName}, \param{wxDbColInf *}{colInf}, \param{int}{nocols}}
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 wxDb::GetColumns() 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 wxDb::GetColumns()). This function populates the PkCol, PkTableName, and FkTableName members of the colInf structure.}
\docparam{nocols}{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{HSTMT}{GetNext}{\void}
Requests the next row in the result set obtained by issueing a query through a direct request using wxDb::ExecSql().
\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}{A handle to the ODBC connection. Pass this in if the ODBC function call that
erred out required a hdbc or hstmt argument.}
\docparam{AHstmt}{A handle to the ODBC statement being executed against. Pass this in if the
ODBC function call that erred out requires a hstmt argument.}
\wxheading{See also}
\helpref{wxDb::DispNextError}{wxdbdispnexterror}, \helpref{wxDb::DispAllErrors}{wxdbdispallerrors}
\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::GetPassword}\label{wxdbgetpassword}
\func{char *}{GetPassword}{\void}
Returns the password used to connect to the datasource.
\membersection{wxDb::GetTableCount}\label{wxdbgettablecount}
\func{int}{GetTableCount}{\void}
Returns the number of wxDbTable() instances currently using this data source connection.
\membersection{wxDb::GetUsername}\label{wxdbgetusername}
\func{char *}{GetUsername}{\void}
Returns the user name used to access the datasource.
\membersection{wxDb::Grant}\label{wxdbgrant}
\func{bool}{Grant}{\param{int}{ privileges}, \param{char *}{tableName}, \param{char *}{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}{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.
\wxheading{Example}
\begin{verbatim}
db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
\end{verbatim}
\membersection{wxDb::IsOpen}\label{wxdbisopen}
\func{bool}{IsOpen}{\void}
Indicates whether the database connection to the datasource is currently opened.
\membersection{wxDb::Open}\label{wxdbopen}
\func{bool}{Open}{\param{char *}{Dsn}, \param{char *}{Uid}, \param{char *}{AuthStr}}
\wxheading{Parameters}
\docparam{Dsn}{Data source name. The name of the ODBC data source as
assigned when the data source 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 data source. 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 witht the Uid.}
\wxheading{Remarks}
After a wxDb instance is created, it must then be opened. When opening a data source, there must be hree pieces of information passed. The data source name, user name (ID) and the password for the user. No database activity on the data source can be performed until it is opened. This would normally be done at program startup and the data source would remain open for the duration of the program run. Note: It is possible to have multiple data sources open at the same time to support distributed database connections.
\wxheading{Example}
\begin{verbatim}
wxDb sampleDB(Db.Henv);
if (!sampleDB.Open("Oracle 7.1 HP/UX", "gtasker", "myPassword"))
{
// Error opening data source
}
\end{verbatim}
\membersection{wxDb::RollbackTrans}\label{wxdbrollbacktrans}
\func{bool}{RollbackTrans}{\void}
Function to "rollback" 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. At any time thereafter, you can save your work to the database (using \helpref{wxDb::CommitTrans}{wxdbcommittrans}) or undo all of your changes using this function.
\normalbox{Calling this member function rolls back ALL open (uncommitted) transactions on this ODBC connection.}
\wxheading{See also}
\helpref{wxDb::CommitTrans}{wxdbcommittrans} for a special note on cursors
\membersection{wxDb::SetSqlLogging}\label{wxdbsetsqllogging}
\func{bool}{SetSqlLogging}{\param{wxDbSqlLogState}{ state}, \param{const wxChar *}{filename = SQL_LOG_FILENAME}, \param{bool}{ append = FALSE}}
\wxheading{Parameters}
\docparam{state}{Either sqlLogOFF or sqlLogON (see \helpref{enum wxDbSqlLogState}{wxdbenumsqllogstate}). Turns logging of SQL commands sent to the data
source OFF or ON.}
\docparam{filename}{{\it OPTIONAL}. Name of the file to which the log text is to be written.}
\docparam{append}{{\it OPTIONAL}. Whether the file is appended to or overwritten.}
\wxheading{Remarks}
When called with {\it sqlLogON}, all commands sent to the data source engine are logged to the file specified by {\it filename}. Logging is done by embedded WriteSqlLog() calls in the database member functions, or may be manually logged by adding calls to WriteSqlLog() in your own source code.
When called with {\it sqlLogOFF}, the logging file is closed, and any calls to WriteSqlLog() are ignored.
\membersection{wxDb::TableExists}\label{wxdbtablexists}
\func{bool}{TableExists}{\param{const char *}{tableName}, \param{const char *}{userID=NULL}, \param{const char *}{path=NULL}}
Checks the ODBC data source 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. 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 privleges to query or perform other functions on the table.
\membersection{wxDb::TranslateSqlState}\label{wxdbtranslatesqlstate}
\func{int}{TranslateSqlState}{\param{const wxChar *}{SQLState}}
\wxheading{Parameters}
\docparam{SQLState}{Converts an ODBC sqlstate to an internal error code.}
\wxheading{Return value}
Returns the internal class DB_ERR code. See \helpref{wxDb::DB_STATUS}{wxdbdbstatus} definition.
\membersection{wxDb::WriteSqlLog}\label{wxdbwritesqllog}
\func{bool}{WriteSqlLog}{\param{const wxChar *}{logMsg}}
\wxheading{Parameters}
\docparam{logMsg}{Free form string to be written to the log file.}
\wxheading{Remarks}
Very useful debugging tool that may be turned on/off during run time. The
passed in string {\it logMsg} will be written to a log file if SQL logging
is turned on (see \helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging} for details on turning logging on/off).
\wxheading{Return value}
If SQL logging is off when a call to WriteSqlLog() is made, or there is a
failure to write the log message to the log file, the function returns
FALSE without performing the requested log, otherwise TRUE is returned.
\wxheading{See also}
\helpref{wxDb::SetSqlLogging}{wxdbsetsqllogging}
==============
\membersection{wxDb::IsFwdOnlyCursors}\label{wxdbisfwdonlycursors}
\func{bool}{IsFwdOnlyCursors}{\void}
\wxheading{Remarks}
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 forward only cursors, then even if
the datasource and ODBC driver support backward scrolling cursors, then
tables using this database connection can only 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 wxODBC_FWD_ONLY_CURSORS value. This default setting can be overridden
when the wxDb connection is initially created (see \helpref{wxDb constructor}{wxdbconstr}).
\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 capable
of supporting backward scrolling cursors (see note above).
\wxheading{See also}
\helpref{wxDb constructor}{wxdbconstr}
=======
\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 be work with these classes, but these databases
returned by this function have been tested and confirmed to work with
these ODBC classes.
enum wxDBMS includes:
\begin{verbatim}
dbmsUNIDENTIFIED
dbmsORACLE
dbmsSYBASE_ASA
dbmsSYBASE_ASE
dbmsMY_SQL_SERVER
dbmsMY_SQL
dbmsPOSTGRES
dbmsACCESS
dbmsDBASE
dbmsINFORMIX
\end{verbatim}
There are known issues with conformance to the ODBC standards with several
datasources listed above. Please see the overview for specific details on
on which datasource have which issues.
\wxheading{Return value}
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::SetDebugErrorMessages}\label{wxdbsetdebugerrormessages}
\func{void}{SetDebugErrorMessages}{\param{bool}{state}}
\docparam{state}{Either TRUE (debug messages are displayed) or FALSE (debug
messages are not displayed.}
\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 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}{wxdbconstr}
==========
\membersection{wxDb::LogError}\label{wxdblogerror}
\func{void}{LogError}{\param{const char *}{errMsg} \param{const char *}{SQLState=0}}
\docparam{errMsg}{Free-form text to display describing the error to be logged.}
\docparam{SQLState}{Native SQL state error}
\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::GetTypeInfXxxxx}\label{wxdbgettypeinf}
\func{wxDbSqlTypeInfo }{GetTypeInfDate}{\void}
\func{wxDbSqlTypeInfo }{GetTypeInfFloat}{\void}
\func{wxDbSqlTypeInfo }{GetTypeInfInteger}{\void}
\func{wxDbSqlTypeInfo }{GetTypeInfVarchar}{\void}
\wxheading{Remarks}
\wxheading{Return value}
Reference in New Issue View Git Blame Copy Permalink