1 \section{\class{wxDb
}}\label{wxdb
}
3 A wxDb instance is a connection to an ODBC data source which may
4 be opened, closed, and re-opened an unlimited number of times. A
5 database connection allows function to be performed directly on the
6 data source, as well as allowing access to any tables/views defined in
7 the data source to which the user has sufficient privileges.
9 \wxheading{Include files
}
13 \wxheading{Helper classes and data structures
}
15 The following classes and structs are defined in db.cpp/.h for use with the wxDb class.
17 \begin{itemize
}\itemsep=
0pt
18 \item \helpref{wxDbColFor
}{wxdbcolfor
}
19 \item \helpref{wxDbColInf
}{wxdbcolinf
}
20 \item \helpref{wxDbTableInf
}{wxdbtableinf
}
21 \item \helpref{wxDbInf
}{wxdbinf
}
26 NOTE: In a future release, all ODBC class constants will be prefaced with 'wx'
30 wxDB_PATH_MAX Maximum path length allowed to be passed to the ODBC
31 driver to indicate where the data file is located.
33 DB_MAX_COLUMN_NAME_LEN Maximum supported length for the name of a column
35 DB_MAX_ERROR_HISTORY Maximum number of error messages retained in the
36 queue before being overwritten by new errors.
38 DB_MAX_ERROR_MSG_LEN Maximum supported length of an error message returned
41 DB_MAX_STATEMENT_LEN Maximum supported length for a complete SQL statement
42 to be passed to the ODBC driver
44 DB_MAX_TABLE_NAME_LEN Maximum supported length for the name of a table
46 DB_MAX_WHERE_CLAUSE_LEN Maximum supported WHERE clause length that can be
47 passed to the ODBC driver
49 DB_TYPE_NAME_LEN Maximum length of the name of a column's data type
53 \wxheading{Enumerated types
}
55 \docparam{enum
{\bf wxDbSqlLogState
}}{sqlLogOFF, sqlLogON
}
57 {\it enum
{\bf wxDBMS
}}
59 These are the databases currently tested and working with the ODBC classes. A call to
\helpref{wxDb::Dbms
}{wxdbdbms
} will return one of these enumerated values listed below.
64 dbmsSYBASE_ASA // Adaptive Server Anywhere
65 dbmsSYBASE_ASE // Adaptive Server Enterprise
76 See the remarks in
\helpref{wxDb::Dbms
}{wxdbdbms
} for exceptions/issues with each of these database engines.
78 \wxheading{Public member variables
}
80 \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.
}
82 \docparam{int
{\bf wxDb::DB
\_STATUS}}{The last ODBC error that occurred on this data connection. Possible codes are:
}
85 DB_ERR_GENERAL_WARNING // SqlState = '
01000'
86 DB_ERR_DISCONNECT_ERROR // SqlState = '
01002'
87 DB_ERR_DATA_TRUNCATED // SqlState = '
01004'
88 DB_ERR_PRIV_NOT_REVOKED // SqlState = '
01006'
89 DB_ERR_INVALID_CONN_STR_ATTR // SqlState = '
01S00'
90 DB_ERR_ERROR_IN_ROW // SqlState = '
01S01'
91 DB_ERR_OPTION_VALUE_CHANGED // SqlState = '
01S02'
92 DB_ERR_NO_ROWS_UPD_OR_DEL // SqlState = '
01S03'
93 DB_ERR_MULTI_ROWS_UPD_OR_DEL // SqlState = '
01S04'
94 DB_ERR_WRONG_NO_OF_PARAMS // SqlState = '
07001'
95 DB_ERR_DATA_TYPE_ATTR_VIOL // SqlState = '
07006'
96 DB_ERR_UNABLE_TO_CONNECT // SqlState = '
08001'
97 DB_ERR_CONNECTION_IN_USE // SqlState = '
08002'
98 DB_ERR_CONNECTION_NOT_OPEN // SqlState = '
08003'
99 DB_ERR_REJECTED_CONNECTION // SqlState = '
08004'
100 DB_ERR_CONN_FAIL_IN_TRANS // SqlState = '
08007'
101 DB_ERR_COMM_LINK_FAILURE // SqlState = '
08S01'
102 DB_ERR_INSERT_VALUE_LIST_MISMATCH // SqlState = '
21S01'
103 DB_ERR_DERIVED_TABLE_MISMATCH // SqlState = '
21S02'
104 DB_ERR_STRING_RIGHT_TRUNC // SqlState = '
22001'
105 DB_ERR_NUMERIC_VALUE_OUT_OF_RNG // SqlState = '
22003'
106 DB_ERR_ERROR_IN_ASSIGNMENT // SqlState = '
22005'
107 DB_ERR_DATETIME_FLD_OVERFLOW // SqlState = '
22008'
108 DB_ERR_DIVIDE_BY_ZERO // SqlState = '
22012'
109 DB_ERR_STR_DATA_LENGTH_MISMATCH // SqlState = '
22026'
110 DB_ERR_INTEGRITY_CONSTRAINT_VIOL // SqlState = '
23000'
111 DB_ERR_INVALID_CURSOR_STATE // SqlState = '
24000'
112 DB_ERR_INVALID_TRANS_STATE // SqlState = '
25000'
113 DB_ERR_INVALID_AUTH_SPEC // SqlState = '
28000'
114 DB_ERR_INVALID_CURSOR_NAME // SqlState = '
34000'
115 DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL // SqlState = '
37000'
116 DB_ERR_DUPLICATE_CURSOR_NAME // SqlState = '
3C000'
117 DB_ERR_SERIALIZATION_FAILURE // SqlState = '
40001'
118 DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL2 // SqlState = '
42000'
119 DB_ERR_OPERATION_ABORTED // SqlState = '
70100'
120 DB_ERR_UNSUPPORTED_FUNCTION // SqlState = 'IM001'
121 DB_ERR_NO_DATA_SOURCE // SqlState = 'IM002'
122 DB_ERR_DRIVER_LOAD_ERROR // SqlState = 'IM003'
123 DB_ERR_SQLALLOCENV_FAILED // SqlState = 'IM004'
124 DB_ERR_SQLALLOCCONNECT_FAILED // SqlState = 'IM005'
125 DB_ERR_SQLSETCONNECTOPTION_FAILED // SqlState = 'IM006'
126 DB_ERR_NO_DATA_SOURCE_DLG_PROHIB // SqlState = 'IM007'
127 DB_ERR_DIALOG_FAILED // SqlState = 'IM008'
128 DB_ERR_UNABLE_TO_LOAD_TRANSLATION_DLL // SqlState = 'IM009'
129 DB_ERR_DATA_SOURCE_NAME_TOO_LONG // SqlState = 'IM010'
130 DB_ERR_DRIVER_NAME_TOO_LONG // SqlState = 'IM011'
131 DB_ERR_DRIVER_KEYWORD_SYNTAX_ERROR // SqlState = 'IM012'
132 DB_ERR_TRACE_FILE_ERROR // SqlState = 'IM013'
133 DB_ERR_TABLE_OR_VIEW_ALREADY_EXISTS // SqlState = 'S0001'
134 DB_ERR_TABLE_NOT_FOUND // SqlState = 'S0002'
135 DB_ERR_INDEX_ALREADY_EXISTS // SqlState = 'S0011'
136 DB_ERR_INDEX_NOT_FOUND // SqlState = 'S0012'
137 DB_ERR_COLUMN_ALREADY_EXISTS // SqlState = 'S0021'
138 DB_ERR_COLUMN_NOT_FOUND // SqlState = 'S0022'
139 DB_ERR_NO_DEFAULT_FOR_COLUMN // SqlState = 'S0023'
140 DB_ERR_GENERAL_ERROR // SqlState = 'S1000'
141 DB_ERR_MEMORY_ALLOCATION_FAILURE // SqlState = 'S1001'
142 DB_ERR_INVALID_COLUMN_NUMBER // SqlState = 'S1002'
143 DB_ERR_PROGRAM_TYPE_OUT_OF_RANGE // SqlState = 'S1003'
144 DB_ERR_SQL_DATA_TYPE_OUT_OF_RANGE // SqlState = 'S1004'
145 DB_ERR_OPERATION_CANCELLED // SqlState = 'S1008'
146 DB_ERR_INVALID_ARGUMENT_VALUE // SqlState = 'S1009'
147 DB_ERR_FUNCTION_SEQUENCE_ERROR // SqlState = 'S1010'
148 DB_ERR_OPERATION_INVALID_AT_THIS_TIME // SqlState = 'S1011'
149 DB_ERR_INVALID_TRANS_OPERATION_CODE // SqlState = 'S1012'
150 DB_ERR_NO_CURSOR_NAME_AVAIL // SqlState = 'S1015'
151 DB_ERR_INVALID_STR_OR_BUF_LEN // SqlState = 'S1090'
152 DB_ERR_DESCRIPTOR_TYPE_OUT_OF_RANGE // SqlState = 'S1091'
153 DB_ERR_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1092'
154 DB_ERR_INVALID_PARAM_NO // SqlState = 'S1093'
155 DB_ERR_INVALID_SCALE_VALUE // SqlState = 'S1094'
156 DB_ERR_FUNCTION_TYPE_OUT_OF_RANGE // SqlState = 'S1095'
157 DB_ERR_INF_TYPE_OUT_OF_RANGE // SqlState = 'S1096'
158 DB_ERR_COLUMN_TYPE_OUT_OF_RANGE // SqlState = 'S1097'
159 DB_ERR_SCOPE_TYPE_OUT_OF_RANGE // SqlState = 'S1098'
160 DB_ERR_NULLABLE_TYPE_OUT_OF_RANGE // SqlState = 'S1099'
161 DB_ERR_UNIQUENESS_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1100'
162 DB_ERR_ACCURACY_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1101'
163 DB_ERR_DIRECTION_OPTION_OUT_OF_RANGE // SqlState = 'S1103'
164 DB_ERR_INVALID_PRECISION_VALUE // SqlState = 'S1104'
165 DB_ERR_INVALID_PARAM_TYPE // SqlState = 'S1105'
166 DB_ERR_FETCH_TYPE_OUT_OF_RANGE // SqlState = 'S1106'
167 DB_ERR_ROW_VALUE_OUT_OF_RANGE // SqlState = 'S1107'
168 DB_ERR_CONCURRENCY_OPTION_OUT_OF_RANGE // SqlState = 'S1108'
169 DB_ERR_INVALID_CURSOR_POSITION // SqlState = 'S1109'
170 DB_ERR_INVALID_DRIVER_COMPLETION // SqlState = 'S1110'
171 DB_ERR_INVALID_BOOKMARK_VALUE // SqlState = 'S1111'
172 DB_ERR_DRIVER_NOT_CAPABLE // SqlState = 'S1C00'
173 DB_ERR_TIMEOUT_EXPIRED // SqlState = 'S1T00'
176 \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 wxDbTable::IsCursorClosedOnCommit() has been added for ease of use.
}
179 char dbmsName
[40] - Name of the dbms product
180 char dbmsVer
[64] - Version # of the dbms product
181 char driverName
[40] - Driver name
182 char odbcVer
[60] - ODBC version of the driver
183 char drvMgrOdbcVer
[60] - ODBC version of the driver manager
184 char driverVer
[60] - Driver version
185 char serverName
[80] - Server Name, typically a connect string
186 char databaseName
[128] - Database filename
187 char outerJoins
[2] - Does datasource support outer joins
188 char procedureSupport
[2] - Does datasource support stored procedures
189 UWORD maxConnections - Maximum # of connections datasource supports
190 UWORD maxStmts - Maximum # of HSTMTs per HDBC
191 UWORD apiConfLvl - ODBC API conformance level
192 UWORD cliConfLvl - Is datasource SAG compliant
193 UWORD sqlConfLvl - SQL conformance level
194 UWORD cursorCommitBehavior - How cursors are affected on db commit
195 UWORD cursorRollbackBehavior - How cursors are affected on db rollback
196 UWORD supportNotNullClause - Does datasource support NOT NULL clause
197 char supportIEF
[2] - Integrity Enhancement Facility (Ref. Integrity)
198 UDWORD txnIsolation - Transaction isolation level supported by driver
199 UDWORD txnIsolationOptions - Transaction isolation level options available
200 UDWORD fetchDirections - Fetch directions supported
201 UDWORD lockTypes - Lock types supported in SQLSetPos
202 UDWORD posOperations - Position operations supported in SQLSetPos
203 UDWORD posStmts - Position statements supported
204 UDWORD scrollConcurrency - Scrollable cursor concurrency options supported
205 UDWORD scrollOptions - Scrollable cursor options supported
206 UDWORD staticSensitivity - Can additions/deletions/updates be detected
207 UWORD txnCapable - Indicates if datasource supports transactions
208 UDWORD loginTimeout - Number seconds to wait for a login request
211 \docparam{char
{\bf wxDb::errorList
}[DB_MAX_ERROR_HISTORY
][DB_MAX_ERROR_MSG_LEN
]}{The last n ODBC errors that have occurred on this database connection.
}
213 \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.
}
215 \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.
}
217 \docparam{wxChar
{\bf wxDb::sqlState
}[20]}{Set by wxDb::TranslateSqlState(). Indicates the error state after a failed ODBC operation. Used for reporting ODBC errors.
}
221 Default cursor scrolling is defined by wxODBC_FWD_ONLY_CURSORS in setup.h
222 when the wxWindows library is built. This behavior can be overridden when
223 an instance of a wxDb is created (see
\helpref{wxDb constructor
}{wxdbconstr
}).
227 \helpref{wxDbColFor
}{wxdbcolfor
},
\helpref{wxDbColInf
}{wxdbcolinf
},
\helpref{wxDbTable
}{wxdbtable
},
\helpref{wxDbTableInf
}{wxdbtableinf
},
\helpref{wxDbInf
}{wxdbinf
}
229 \subsection{Associated non-class functions
}\label{wxdbfunctions
}
231 The following functions are used in conjunction with the wxDb class.
233 \func{wxDb *
}{wxDbGetConnection
}{\param{wxDbConnectInf *
}{pDbConfig
},
\param{bool
}{FwdOnlyCursors=(bool)wxODBC_FWD_ONLY_CURSORS
}}
235 \func{bool
}{wxDbFreeConnection
}{\param{wxDb *
}{pDb
}}
237 \func{void
}{wxDbCloseConnections
}{\void}
239 \func{int
}{wxDbConnectionsInUse
}{\void}
241 \func{bool
}{wxDbSqlLog
}{\param{wxDbSqlLogState
}{state
},
\param{const wxChar *
}{filename = SQL_LOG_FILENAME
}}
243 \func{bool
}{wxDbGetDataSource
}{\param{HENV
}{henv
},
\param{char *
}{Dsn
},
\param{SWORD
}{DsnMax
},
\param{char *
}{DsDesc
},
\param{SWORD
}{DsDescMax
},
\param{UWORD
}{direction = SQL_FETCH_NEXT
}}
245 \latexignore{\rtfignore{\wxheading{Members
}}}
247 \membersection{wxDb::wxDb
}\label{wxdbconstr
}
253 \func{}{wxDb
}{\param{HENV &
}{aHenv
},
\param{bool
}{FwdOnlyCursors=(bool)wxODBC_FWD_ONLY_CURSORS
}}
255 Constructor, used to create an ODBC connection to a data source.
257 \wxheading{Parameters
}
259 \docparam{aHenv
}{Environment handle used for this connection.
}
261 \docparam{FwdOnlyCursors
}{Will cursors created for use with this datasource connection only allow forward scrolling cursors.
}
265 This is the constructor for the wxDb class. The wxDb object must
266 be created and opened before any database activity can occur.
271 wxDbConnectInf ConnectInf;
272 ....Set values for member variables of ConnectInf here
274 wxDb sampleDB(ConnectInf.Henv);
275 if (!sampleDB.Open(ConnectInf.Dsn, ConnectInf.Uid, ConnectInf.AuthStr))
277 // Error opening data source
282 \membersection{wxDb::Catalog
}\label{wxdbcatalog
}
284 \func{bool
}{Catalog
}{\param{char *
}{ userID
},
\param{char *
}{fileName = SQL_CATALOG_FILENAME
}}
286 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.
288 \wxheading{Parameters
}
290 \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.
}
292 \docparam{fileName
}{{\it OPTIONAL
}. Name of the text file to create and write the DB catalog to.
}
294 \wxheading{Return value
}
296 Returns TRUE if the catalog request was successful, of FALSE if there was some reason the catalog could not be generated
301 ============== ============== ================ ========= =======
302 TABLE NAME COLUMN NAME DATA TYPE PRECISION LENGTH
303 ============== ============== ================ ========= =======
304 EMPLOYEE RECID (
0008)NUMBER
15 8
305 EMPLOYEE USER_ID (
0012)VARCHAR2
13 13
306 EMPLOYEE FULL_NAME (
0012)VARCHAR2
26 26
307 EMPLOYEE PASSWORD (
0012)VARCHAR2
26 26
308 EMPLOYEE START_DATE (
0011)DATE
19 16
312 \membersection{wxDb::Close
}\label{wxdbclose
}
314 \func{void
}{Close
}{\void}
316 Closes the database connection.
320 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.
322 Any wxDbTable instances which use this connection must be deleted before closing the database connection.
327 // Commit any open transactions on the data source
328 sampleDB.CommitTrans();
330 // Delete any remaining wxDbTable objects allocated with new
333 // Close the wxDb connection when finished with it
336 // Free Environment Handle that ODBC uses
337 if (SQLFreeEnv(Db.Henv) != SQL_SUCCESS)
339 // Error freeing environment handle
344 \membersection{wxDb::CommitTrans
}\label{wxdbcommittrans
}
346 \func{bool
}{CommitTrans
}{\void}
348 Permanently "commits" changes (insertions/deletions/updates) to the database.
350 \wxheading{Return value
}
352 Returns TRUE if the commit was successful, or FALSE if the commit failed.
356 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.
358 \wxheading{Special Note :
{\it Cursors
} }
360 \normalbox{It is important to understand that different database/ODBC driver combinations handle
361 transactions differently. One thing in particular that you must pay attention to is
362 cursors, in regard to transactions. Cursors are what allow you to scroll through
363 records forward and backward and to manipulate records as you scroll through them.
364 When you issue a query, a cursor is created behind the scenes. The cursor keeps track
365 of the query and keeps track of the current record pointer. After you commit or
366 rollback a transaction, the cursor may be closed automatically. This means you must
367 requery the data source before you can perform any additional work against the wxDbTable
368 object. This is only necessary however if the data source closes the cursor after a
369 commit or rollback. Use the wxDbTable::IsCursorClosedOnCommit() member function to
370 determine the data source's transaction behavior. Note, it would be very inefficient
371 to just assume the data source closes the cursor and always requery. This could put
372 a significant, unnecessary load on data sources that leave the cursors open after a
376 \membersection{wxDb::CreateView
}\label{wxdbcreateviews
}
378 \func{bool
}{CreateView
}{\param{char *
}{ viewName
},
\param{char *
}{ colList
},
\param{char *
}{pSqlStmt
}}
382 \wxheading{Parameters
}
384 \docparam{viewName
}{The name of the view. e.g. PARTS_V
}
386 \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.
}
388 \docparam{pSqlStmt
}{Pointer to the select statement portion of the CREATE VIEW statement. Must be a complete, valid SQL SELECT statement.
}
392 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.
394 NOTE: Views are not available with all datasources. Oracle is one example of a datasouce which does support views.
399 // Incomplete code sample
400 db.CreateView("PARTS_SD1", "PN, PD, QTY",
401 "SELECT PART_NO, PART_DESC, QTY_ON_HAND *
1.1 FROM PARTS \
402 WHERE STORAGE_DEVICE =
1");
404 // PARTS_SD1 can now be queried just as if it were a data table.
405 // e.g. SELECT PN, PD, QTY FROM PARTS_SD1
409 \membersection{wxDb::Dbms
}\label{wxdbdbms
}
411 \func{wxDBMS
}{Dbms
}{\void}
415 The return value will be of the enumerated type wxDBMS. This enumerated
416 type contains a list of all the currently tested and supported databases.
418 Additional databases may be work with these classes, but these databases
419 returned by this function have been tested and confirmed to work with
422 enum wxDBMS includes:
437 There are known issues with conformance to the ODBC standards with several
438 datasources listed above. Please see the overview for specific details on
439 which datasource have which issues.
441 \wxheading{Return value
}
443 The return value will indicate which of the supported datasources is
444 currently connected to by this connection. In the event that the
445 datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.
448 \membersection{wxDb::DispAllErrors
}\label{wxdbdispallerrors
}
450 \func{bool
}{DispAllErrors
}{\param{HENV
}{ aHenv
},
{\param}{HDBC
}{ aHdbc = SQL_NULL_HDBC
},
{\param}{HSTMT
}{ aHstmt = SQL_NULL_HSTMT
}}
452 Logs all database errors that occurred as a result of the last executed
453 database command. This logging also includes debug logging when compiled in
454 debug mode via
\helpref{wxLogDebug
}{wxlogdebug
}. If logging is turned on
455 via
\helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
}, then an entry is also
456 logged to the defined log file.
458 \wxheading{Parameters
}
460 \docparam{aHenv
}{A handle to the ODBC environment.
}
462 \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.
}
464 \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.
}
468 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()).
472 \helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
}, wxDbSqlLog
477 if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
478 // Display all ODBC errors for this stmt
479 return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
483 \membersection{wxDb::DispNextError
}\label{wxdbdispnexterror
}
485 \func{void
}{DispNextError
}{\void}
489 This function is normally used internally within the ODBC class library.
490 It could be used externally if calling ODBC functions directly. This
491 function works in conjunction with
\helpref{wxDb::GetNextError
}{wxdbgetnexterror
} when errors (or
492 sometimes informational messages) returned from ODBC need to be analyzed
493 rather than simply displaying them as an error. GetNextError() retrieves
494 the next ODBC error from the ODBC error queue. The wxDb member variables
495 "sqlState", "nativeError" and "errorMsg" could then be evaluated. To
496 display the error retrieved, DispNextError() could then be called.
497 The combination of GetNextError() and DispNextError() can be used to
498 iteratively step through the errors returned from ODBC evaluating each
499 one in context and displaying the ones you choose.
504 // Drop the table before attempting to create it
505 sprintf(sqlStmt, "DROP TABLE
%s", tableName);
506 // Execute the drop table statement
507 if (SQLExecDirect(hstmt,(UCHAR FAR *)sqlStmt,SQL_NTS) != SQL_SUCCESS)
509 // Check for sqlState = S0002, "Table or view not found".
510 // Ignore this error, bomb out on any other error.
511 pDb->GetNextError(henv, hdbc, hstmt);
512 if (strcmp(pDb->sqlState, "S0002"))
514 pDb->DispNextError(); // Displayed error retrieved
515 pDb->DispAllErrors(henv, hdbc, hstmt); // Display all other errors, if any
516 pDb->RollbackTrans(); // Rollback the transaction
517 CloseCursor(); // Close the cursor
518 return(FALSE); // Return Failure
524 \membersection{wxDb::DropView
}\label{wxdbdropview
}
526 \func{bool
}{DropView
}{\param{const char *
}{viewName
}}
528 Drops the data table view named in 'viewName'.
530 \wxheading{Parameters
}
532 \docparam{viewName
}{Name of the view to be dropped.
}
536 If the view does not exist, this function will return TRUE. Note that views are not supported with all data sources.
538 \membersection{wxDb::ExecSql
}\label{wxdbexecsql
}
540 \func{bool
}{ExecSql
}{\param{char *
}{pSqlStmt
}}
542 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.
544 \wxheading{Parameters
}
546 \docparam{pSqlStmt
}{Pointer to the SQL statement to be executed.
}
550 This member extends the wxDb class and allows you to build and execute ANY VALID
551 SQL statement against the data source. This allows you to extend the class
552 library by being able to issue any SQL statement that the data source is capable
557 \helpref{wxDb::GetData
}{wxdbgetdata
},
\helpref{wxDb::GetNext
}{wxdbgetnext
}
559 \membersection{wxDb::FwdOnlyCursors
}\label{wxdbfwdonlycursors
}
561 \func{bool
}{FwdOnlyCursors
}{\void}
563 Indicates whether this connection to the datasource only allows forward scrolling cursors or not. This state is set at connection creation time.
567 In wxWindows v2.4 release, this function will be deprecated to use a renamed version of the function called wxDb::IsFwdOnlyCursors() to match the normal wxWindows naming conventions for class member functions.
571 \helpref{wxDb::IsFwdOnlyCursors
}{wxdbisfwdonlycursors
},
\helpref{wxDb::wxDb
}{wxdbconstr
},
\helpref{wxDbGetConnection
}{wxdbfunctions
}
573 \membersection{wxDb::GetCatalog
}\label{wxdbgetcatalog
}
575 \func{wxDbInf *
}{GetCatalog
}{\param{char *
}{userID
}}
577 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.
579 \wxheading{Parameters
}
581 \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:
}
584 userID == NULL ... UserID is ignored (DEFAULT)
585 userID == "" ... UserID set equal to 'this->uid'
586 userID != "" ... UserID set equal to 'userID'
591 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.
593 \membersection{wxDb::GetColumnCount
}\label{wxdbgetcolumncount
}
595 \func{int
}{GetColumnCount
}{\param{char *
}{tableName
},
\param{const char *
}{userID
}}
597 \wxheading{Parameters
}
599 \docparam{tableName
}{A table name you wish to obtain column information about.
}
601 \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:
}
604 userID == NULL ... UserID is ignored (DEFAULT)
605 userID == "" ... UserID set equal to 'this->uid'
606 userID != "" ... UserID set equal to 'userID'
609 \wxheading{Return value
}
611 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.
613 \membersection{wxDb::GetColumns
}\label{wxdbgetcolumns
}
615 \func{wxDbColInf *
}{GetColumns
}{\param{char *
}{tableName
},
\param{int *
}{numCols
},
\param{const char *
}{userID=NULL
}}
617 \func{wxDbColInf *
}{GetColumns
}{\param{char *
}{tableName
[]},
\param{const char *
}{userID
}}
619 \wxheading{Parameters
}
621 \docparam{tableName
}{A table name you wish to obtain column information about.
}
622 \docparam{numCols
}{A pointer to a integer which will hold a count of the number of columns returned by this function
}
623 \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.
}
624 \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:
}
627 userID == NULL ... UserID is ignored (DEFAULT)
628 userID == "" ... UserID set equal to 'this->uid'
629 userID != "" ... UserID set equal to 'userID'
632 \wxheading{Return value
}
634 This function returns an array of wxDbColInf structures. This allows you to obtain
635 information regarding the columns of your table(s). If no columns were found, or
636 an error occurred, this pointer will be zero (null).
638 THE CALLING FUNCTION IS RESPONSIBLE FOR DELETING THE
{\it wxDbColInf
} MEMORY WHEN IT IS
641 \normalbox{ALL column bindings associated with this wxDb instance are unbound
642 by this function. This function should use its own wxDb instance
643 to avoid undesired unbinding of columns.
}
647 \helpref{wxDbColInf
}{wxdbcolinf
}
652 char *tableList
[] =
{"PARTS",
0};
653 wxDbColInf *colInf = pDb->GetColumns(tableList);
656 // Use the column inf
658 // Destroy the memory
664 \membersection{wxDb::GetData
}\label{wxdbgetdata
}
666 \func{bool
}{GetData
}{\param{UWORD
}{ colNo
},
\param{SWORD
}{ cType
},
\param{PTR
}{ pData
},
\param{SDWORD
}{ maxLen
},
\param{SDWORD FAR *
}{ cbReturned
} }
668 Used to retrieve result set data without binding column values to memory variables (i.e. not using a wxDbTable instance to access table data).
670 \wxheading{Parameters
}
672 \docparam{colNo
}{Ordinal number of column in the result set to be returned.
}
673 \docparam{cType
}{The C data type that is to be returned.
}
674 \docparam{pData
}{Memory buffer which will hold the data returned by the call to this function.
}
675 \docparam{maxLen
}{Maximum size of the buffer that will hold the returned value.
}
676 \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.
}
680 \helpref{wxDb::GetNext
}{wxdbgetnext
},
\helpref{wxDb::ExecSql
}{wxdbexecsql
}
688 sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
689 PART_RECID =
1450 AND REQUIRED_QTY > PICKED_QTY";
692 if (!pDb->ExecSql(sqlStmt.c_str()))
698 // Request the first row of the result set
705 Read column
#1 of this row of the result set and store the value in 'reqQty'
706 if (!pDb->GetData(
1, SQL_C_ULONG, &reqQty,
0, &cb))
712 // Check for a NULL result
713 if (cb == SQL_NULL_DATA)
719 When requesting multiple columns to be returned from the result set (for example, the SQL query
720 requested
3 columns be returned), the calls to this function must request the columns in ordinal
721 sequence (
1,
2,
3 or
1,
3 or
2,
3).
723 \membersection{wxDb::GetDatabaseName
}\label{wxdbgetdatabasename
}
725 \func{const char *
}{GetDatabaseName
}{\void}
727 Returns the name of the database engine.
729 \membersection{wxDb::GetDataSource
}\label{wxdbgetdatasource
}
731 \func{const char *
}{GetDataSource
}{\void}
733 Returns the ODBC datasource name.
735 \membersection{wxDb::GetHDBC
}\label{wxdbgethdbc
}
737 \func{HDBC
}{GetHDBC
}{\void}
739 Returns the ODBC handle to the database connection.
741 \membersection{wxDb::GetHENV
}\label{wxdbgethenv
}
743 \func{HENV
}{GetHENV
}{\void}
745 Returns the ODBC environment handle.
747 \membersection{wxDb::GetHSTMT
}\label{wxdbgethstmt
}
749 \func{HSTMT
}{GetHSTMT
}{\void}
751 Returns the ODBC statement handle associated with this database connection.
753 \membersection{wxDb::GetKeyFields
}\label{wxdbgetkeyfields
}
755 \func{int
}{GetKeyFields
}{\param{char *
}{tableName
},
\param{wxDbColInf *
}{colInf
},
\param{int
}{nocols
}}
757 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.
759 This function is primarily for use by the
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
} function, but may be called if desired from the client application.
761 \wxheading{Parameters
}
763 \docparam{tableName
}{Name of the table for which the columns will be evaluated as to their inclusion in any indexes.
}
764 \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.
}
765 \docparam{nocols
}{Number of columns defined in the instance of colInf.
}
767 \wxheading{Return value
}
769 Currently always returns TRUE.
773 \helpref{wxDbColInf
}{wxdbcolinf
},
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
}
775 \membersection{wxDb::GetNext
}\label{wxdbgetnext
}
777 \func{bool
}{GetNext
}{\void}
779 Requests the next row in the result set obtained by issuing a query through a direct request using wxDb::ExecSql().
783 \helpref{wxDb::ExecSql
}{wxdbexecsql
},
\helpref{wxDb::GetData
}{wxdbgetdata
}
785 \membersection{wxDb::GetNextError
}\label{wxdbgetnexterror
}
787 \func{bool
}{GetNextError
}{\param{HENV
}{ aHenv
},
\param{HDBC
}{ aHdbc = SQL_NULL_HDBC
},
\param{HSTMT
}{ aHstmt = SQL_NULL_HSTMT
}}
789 \wxheading{Parameters
}
791 \docparam{aHenv
}{A handle to the ODBC environment.
}
792 \docparam{aHdbc
}{A handle to the ODBC connection. Pass this in if the ODBC function call that
793 erred out required a hdbc or hstmt argument.
}
794 \docparam{AHstmt
}{A handle to the ODBC statement being executed against. Pass this in if the
795 ODBC function call that erred out requires a hstmt argument.
}
799 \helpref{wxDb::DispNextError
}{wxdbdispnexterror
},
\helpref{wxDb::DispAllErrors
}{wxdbdispallerrors
}
804 if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
806 // Display all ODBC errors for this stmt
807 return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
812 \membersection{wxDb::GetPassword
}\label{wxdbgetpassword
}
814 \func{const char *
}{GetPassword
}{\void}
816 Returns the password used to connect to the datasource.
818 \membersection{wxDb::GetTableCount
}\label{wxdbgettablecount
}
820 \func{int
}{GetTableCount
}{\void}
822 Returns the number of wxDbTable() instances currently using this data source connection.
825 \membersection{wxDb::GetUsername
}\label{wxdbgetusername
}
827 \func{const char *
}{GetUsername
}{\void}
829 Returns the user name used to access the datasource.
832 \membersection{wxDb::Grant
}\label{wxdbgrant
}
834 \func{bool
}{Grant
}{\param{int
}{ privileges
},
\param{char *
}{tableName
},
\param{char *
}{userList = "PUBLIC"
}}
836 Use this member function to GRANT privileges to users for accessing tables in the datasource.
838 \wxheading{Parameters
}
840 \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:
}
847 DB_GRANT_ALL = DB_GRANT_SELECT | DB_GRANT_INSERT |
848 DB_GRANT_UPDATE | DB_GRANT_DELETE
851 \docparam{tableName
}{The name of the table you wish to grant privileges on.
}
852 \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.
}
856 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.
861 db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
865 \membersection{wxDb::IsFwdOnlyCursors
}\label{wxdbisfwdonlycursors
}
867 \func{bool
}{IsFwdOnlyCursors
}{\void}
869 This setting indicates whether this database connection was created
870 as being capable of using only forward scrolling cursors. This function
871 does NOT indicate if the ODBC driver or datasource supports backward
872 scrolling cursors. There is no standard way of detecting if the driver
873 or datasource can support backward scrolling cursors.
875 If a wxDb instance was created as being forward only cursors, then even if
876 the datasource and ODBC driver support backward scrolling cursors, then
877 tables using this database connection can only use forward scrolling
880 The default setting of whether a wxDb connection to a database allows
881 forward-only or also backward scrolling cursors is defined in setup.h by
882 the wxODBC_FWD_ONLY_CURSORS value. This default setting can be overridden
883 when the wxDb connection is initially created (see
\helpref{wxDb constructor
}{wxdbconstr
}).
885 \wxheading{Return value
}
887 Returns TRUE if this datasource connection is defined as using only forward
888 scrolling cursors, or FALSE if the connection is defined as being capable
889 of supporting backward scrolling cursors (see note above).
893 Added as of wxWindows v2.4 release, this function is a renamed version of
894 wxDb::FwdOnlyCursors() to match the normal wxWindows naming conventions for
895 class member functions.
897 This function is not available in versions prior to v2.4. You should use
\helpref{wxDb::FwdOnlyCursors
}{wxdbfwdonlycursors
} for wxWindows versions priori to
2.4.
901 \helpref{wxDb constructor
}{wxdbconstr
},
\helpref{wxDbGetConnection
}{wxdbfunctions
}
904 \membersection{wxDb::IsOpen
}\label{wxdbisopen
}
906 \func{bool
}{IsOpen
}{\void}
908 Indicates whether the database connection to the datasource is currently
913 This function may indicate that the database is open, but the call to
914 \helpref{wxDb::Open
}{wxdbopen
} may have failed to fully initialize the connection
915 correctly. The connection to the database
{\it is
} open and can be used via
916 the direct SQL commands, but other functions which depend on the
\helpref{wxDb::Open
}{wxdbopen
}
917 to have completed correctly may not function as expected. See
\helpref{wxDb::Open
}{wxdbopen
}
918 for more details on partial failures to open a connection instance.
921 \membersection{wxDb::LogError
}\label{wxdblogerror
}
923 \func{void
}{LogError
}{\param{const char *
}{errMsg
} \param{const char *
}{SQLState=
0}}
925 \docparam{errMsg
}{Free-form text to display describing the error to be logged.
}
926 \docparam{SQLState
}{Native SQL state error
}
930 Calling this function will enter a log message in the error list maintained
931 for the database connection. This log message is free form and can be
932 anything the programmer wants to enter in the error list.
934 If SQL logging is turned on, the call to this function will also log the
935 text into the SQL log file.
939 \helpref{wxDb::WriteSqlLog
}{wxdbwritesqllog
}
942 \membersection{wxDb::Open
}\label{wxdbopen
}
944 \func{bool
}{Open
}{\param{char *
}{Dsn
},
\param{char *
}{Uid
},
\param{char *
}{AuthStr
}}
945 \func{bool
}{Open
}{\param{wxDb *
}{copyDb
}}
947 Opens a connection to the datasource, sets behaviors of all databases to
948 confirm to the accepted behaviors (e.g. cursor position maintained on commits),
949 and queries the datasource for its representations of the basic datatypes to
950 determine the form that data going to/from columns in the data tables are
953 The second form of this function which accepts a "wxDb *" as a parameter
954 can be used to avoid the overhead (execution time, database load, network
955 traffic) which are needed to determine the data types and representations
956 of data that are necessary for cross-datasource support by these classes.
957 Normally the first form of the wxDb::Open() function will open the connection
958 and then send a series of queries to the datasource asking it for its
959 representation of data types, and all the features it supports. If one
960 connection to the datasource has already been made previously, the information
961 gathered when that connection was created can just be copied to any new
962 connections to the same datasource by passing a pointer to the first
963 connection in as a parameter to the wxDb::Open() function. Note that this
964 new connection created from the first connections information will use the
965 same Dsn/Uid/AuthStr as the first connection used.
967 \wxheading{Parameters
}
969 \docparam{Dsn
}{Data source name. The name of the ODBC data source as
970 assigned when the data source is initially set up through the ODBC data
972 \docparam{Uid
}{User ID. The name (ID) of the user you wish to connect as
973 to the data source. The user name (ID) determines what objects you
974 have access to in the datasource and what datasource privileges you have.
975 Privileges include being able to create new objects, update objects, delete
976 objects and so on. Users and privileges are normally administered by the
977 database administrator.
}
978 \docparam{AuthStr
}{The password associated with the Uid.
}
979 \docparam{copyDb
}{Already completely configured and opened datasource
980 connection from which all Dsn, Uid, AuthStr, and data typing information is
981 to be copied from for use by this datasource connection.
}
985 After a wxDb instance is created, it must then be opened. When opening a
986 data source, there must be hree pieces of information passed. The data
987 source name, user name (ID) and the password for the user. No database
988 activity on the data source can be performed until it is opened. This
989 would normally be done at program startup and the data source would remain
990 open for the duration of the program run.
992 It is possible to have multiple data sources open at the same time to
993 support distributed database connections by having separate instances of wxDb
994 objects that use different Dsn/Uid/AuthStr settings.
996 If this function returns a value of FALSE, it does not necessarily mean that
997 the connection to the datasource was not opened. It may mean that some
998 portion of the initialization of the connection failed (such as a datatype not
999 being able to be determined how the datasource represents it). To determine
1000 if the connection to the database failed, use the
\helpref{wxDb::IsOpen
}{wxdbisopen
}
1001 function after receiving a FALSE result back from this function to determine if
1002 the connection was opened or not. If this function returns FALSE, but
\helpref{wxDb::IsOpen
}{wxdbisopen
}
1003 returns TRUE, then direct SQL commands may be passed to the database
1004 connection and they can be successfully executed, but use of the datatypes
1005 that are normally determined during open will not be accessible to any
1006 wxDbTable objects using this connection.
1011 wxDb sampleDB(Db.Henv);
1012 if (!sampleDB.Open("Oracle
7.1 HP/UX", "gtasker", "myPassword"))
1014 // Error opening data source
1019 \membersection{wxDb::RollbackTrans
}\label{wxdbrollbacktrans
}
1021 \func{bool
}{RollbackTrans
}{\void}
1023 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.
1027 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.
1029 \normalbox{Calling this member function rolls back ALL open (uncommitted) transactions on this ODBC connection.
}
1031 \wxheading{See also
}
1033 \helpref{wxDb::CommitTrans
}{wxdbcommittrans
} for a special note on cursors
1036 \membersection{wxDb::SetDebugErrorMessages
}\label{wxdbsetdebugerrormessages
}
1038 \func{void
}{SetDebugErrorMessages
}{\param{bool
}{state
}}
1040 \docparam{state
}{Either TRUE (debug messages are displayed) or FALSE (debug
1041 messages are not displayed.
}
1045 Turns on/off debug error messages from the ODBC class library. When
1046 this function is passed TRUE, errors are reported to the user automatically
1047 in a text or pop-up dialog when an ODBC error occurs. When passed FALSE,
1048 errors are silently handled.
1050 When compiled in release mode (FINAL=
1), this setting has no affect.
1052 \wxheading{See also
}
1054 \helpref{wxDb constructor
}{wxdbconstr
}
1057 \membersection{wxDb::SetSqlLogging
}\label{wxdbsetsqllogging
}
1059 \func{bool
}{SetSqlLogging
}{\param{wxDbSqlLogState
}{ state
},
\param{const wxChar *
}{filename = SQL_LOG_FILENAME
},
\param{bool
}{ append = FALSE
}}
1061 \wxheading{Parameters
}
1063 \docparam{state
}{Either sqlLogOFF or sqlLogON (see
\helpref{enum wxDbSqlLogState
}{wxdbcolfor
}). Turns logging of SQL commands sent to the data source OFF or ON.
}
1064 \docparam{filename
}{{\it OPTIONAL
}. Name of the file to which the log text is to be written.
}
1065 \docparam{append
}{{\it OPTIONAL
}. Whether the file is appended to or overwritten.
}
1069 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.
1071 When called with
{\it sqlLogOFF
}, the logging file is closed, and any calls to WriteSqlLog() are ignored.
1074 \membersection{wxDb::TableExists
}\label{wxdbtablexists
}
1076 \func{bool
}{TableExists
}{\param{const char *
}{tableName
},
\param{const char *
}{userID=NULL
},
\param{const char *
}{path=NULL
}}
1078 Checks the ODBC data source for the existence of a table. If a
{\it userID
}
1079 is specified, then the table must be accessible by that user (user must have
1080 at least minimal privileges to the table).
1082 \wxheading{Parameters
}
1084 \docparam{tableName
}{Name of the table to check for the existence of
}
1085 \docparam{userID
}{Owner of the table. Specify a userID when the datasource you are connected
1086 to allows multiple unique tables with the same name to be owned by different users.
{\it userID
}
1087 is evaluated as follows:
}
1090 userID == NULL ... UserID is ignored (DEFAULT)
1091 userID == "" ... UserID set equal to 'this->uid'
1092 userID != "" ... UserID set equal to 'userID'
1097 {\it tableName
} may refer to a table, view, alias or synonym.
1099 This function does not indicate whether or not the user has privileges to query or perform other functions on the table.
1101 \wxheading{See also
}
1103 \helpref{wxDb::TablePrivileges
}{wxdbtableprivileges
}
1106 \membersection{wxDb::TablePrivileges
}\label{wxdbtableprivileges
}
1108 \func{bool
}{TablePrivileges
}{\param{const char *
}{tableName
},
\param{const char *
}{priv
},
\param{const char *
}{userID=NULL
},
\param{const char *
}{path=""
}}
1110 Checks the ODBC data source for the existence of a table. If a
{\it userID
}
1111 is specified, then the table must be accessible by that user (user must have
1112 at least minimal privileges to the table).
1114 \wxheading{Parameters
}
1116 \docparam{tableName
}{Name of the table on which to check privileges.
1117 {\it tableName
} may refer to a table, view, alias or synonym.
}
1118 \docparam{priv
}{The table privilege being evaluated. May be one of the
1119 following (or a data source specific privilege):
}
1122 SELECT : The connected user is permitted to retrieve data for one
1123 or more columns of the table.
1125 INSERT : The connected user is permitted to insert new rows
1126 containing data for one or more columns into the table.
1128 UPDATE : The connected user is permitted to update the data in one
1129 or more columns of the table.
1131 DELETE : The connected user is permitted to delete rows of data
1134 REFERENCES : Is the connected user permitted to refer to one or more
1135 columns of the table within a constraint (for example, a
1136 unique, referential, or table check constraint).
1138 \docparam{userID
}{Owner of the table. Specify a userID when the datasource
1139 you are connected to allows multiple unique tables with the same name to be
1140 owned by different users.
{\it userID
} is evaluated as follows:
1143 userID == NULL ... UserID is ignored (DEFAULT)
1144 userID == "" ... UserID set equal to 'this->uid'
1145 userID != "" ... UserID set equal to 'userID'
1148 \docparam{path
}{{\it OPTIONAL.
} Path to the table. Default is "".
1153 The scope of privilege allowed to the connected user by a given table
1154 privilege is data source dependent.
1156 For example, the privilege UPDATE might allow the connected user to update
1157 all columns in a table on one data source, but only those columns for
1158 which the grantor (the user that granted the connected user) has the UPDATE
1159 privilege on another data source.
1162 \membersection{wxDb::TranslateSqlState
}\label{wxdbtranslatesqlstate
}
1164 \func{int
}{TranslateSqlState
}{\param{const wxChar *
}{SQLState
}}
1166 \wxheading{Parameters
}
1168 \docparam{SQLState
}{Converts an ODBC sqlstate to an internal error code.
}
1170 \wxheading{Return value
}
1172 Returns the internal class DB_ERR code. See
\helpref{wxDb::DB_STATUS
}{wxdb
} definition.
1175 \membersection{wxDb::WriteSqlLog
}\label{wxdbwritesqllog
}
1177 \func{bool
}{WriteSqlLog
}{\param{const wxChar *
}{logMsg
}}
1179 \wxheading{Parameters
}
1181 \docparam{logMsg
}{Free form string to be written to the log file.
}
1185 Very useful debugging tool that may be turned on/off during run time. The
1186 passed in string
{\it logMsg
} will be written to a log file if SQL logging
1187 is turned on (see
\helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
} for details on turning logging on/off).
1189 \wxheading{Return value
}
1191 If SQL logging is off when a call to WriteSqlLog() is made, or there is a
1192 failure to write the log message to the log file, the function returns
1193 FALSE without performing the requested log, otherwise TRUE is returned.
1195 \wxheading{See also
}
1197 \helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
}
1200 \section{\class{wxDbColDataPtr
}}\label{wxdbcoldataptr
}
1202 Pointer to dynamic column definitions for use with a wxDbTable instance.
1203 Currently there are no member functions for this class.
1212 \section{\class{wxDbColDef
}}\label{wxdbcoldef
}
1214 This class is used to hold information about the columns bound to an
1215 instance of a wxDbTable object.
1217 Each instance of this class describes one column in the wxDbTable
1218 object. When calling the
\helpref{wxDb constructor
}{wxdbconstr
}, a
1219 parameter passed in indicates the number of columns that will be defined for
1220 the wxDbTable object. The constructor uses this information to allocate
1221 adequate memory for all of the column descriptions in your wxDbTable object.
1222 Private member wxDbTable::colDefs is a pointer to this chunk of memory
1223 maintained by the wxDbTable class (and can be retrieved using the
1224 \helpref{wxDbTable::GetColDefs
}{wxdbtablegetcoldefs
} function).
1225 To access the nth column definition of your wxDbTable object, just reference
1226 wxDbColDefs element
[n -
1].
1228 Currently there are no member functions for this class.
1230 Typically,
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
} takes care of
1231 populating an array of these data structures for the wxDbTable instance.
1234 char ColName
[DB_MAX_COLUMN_NAME_LEN+
1]; // Column Name
1235 int DbDataType; - Logical Data Type; e.g. DB_DATA_TYPE_INTEGER
1236 int SqlCtype; - C data type; e.g. SQL_C_LONG
1237 void *PtrDataObj; - Address of the data object
1238 int SzDataObj; - Size, in bytes, of the data object
1239 bool KeyField; - Is column part of the PRIMARY KEY for the
1240 table? -- Date fields should NOT be KeyFields
1241 bool Updateable; - Column is updateable?
1242 bool InsertAllowed; - Column included in INSERT statements?
1243 bool DerivedCol; - Column is a derived value?
1244 SDWORD CbValue; - !!!Internal use only!!!
1245 bool Null; - NOT FULLY IMPLEMENTED
1246 Allows NULL values in Inserts and Updates
1249 \wxheading{See also
}
1251 \helpref{wxDbTable::GetColDefs
}{wxdbtablegetcoldefs
},
\helpref{wxDb constructor
}{wxdbconstr
}
1254 \section{\class{wxDbColInf
}}\label{wxdbcolinf
}
1256 Used with the
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
} functions for obtaining all retrievable information about a columns definition.
1259 \section{\class{wxDbColFor
}}\label{wxdbcolfor
}
1261 Beginning support for handling international formatting specifically on dates and floats.
1263 Only one function is provided with this class currently:
1265 \membersection{wxDbColFor::Format
}\label{wxdbcolforformat
}
1267 \func{int
}{Format
}{\param{int
}{Nation
},
\param{int
}{dbDataType
},
\param{SWORD
}{sqlDataType
},
\param{short
}{columnSize
},
\param{short
}{decimalDigits
}}\label{wxdbcolforformat
}
1269 Work in progress, and should be inter-related with wxLocale
1272 \section{\class{wxDbIdxDef
}}\label{wxdbidxdef
}
1274 Used in creation of non-primary indexes. Currently there are no member
1275 functions for this class.
1278 char ColName
[DB_MAX_COLUMN_NAME_LEN+
1] - Name of column
1279 bool Ascending - Are the values in the index in ASCENDING sequence?
1283 \section{\class{wxDbInf
}}\label{wxdbinf
}
1285 Contains information regarding the database connection (data source name,
1286 number of tables, etc). A pointer to a wxDbTableInf is included in this
1287 class so a program can create a wxDbTableInf array instance to maintain all
1288 information about all tables in the datasource to have all the datasource's
1289 information in one memory structure.
1292 \section{\class{wxDbTable
}}\label{wxdbtable
}
1294 A wxDbTable instance provides re-usable access to rows of data in
1295 a table contained within the associated ODBC data source
1297 \wxheading{Include files
}
1302 \latexignore{\rtfignore{\wxheading{Members
}}}
1303 \wxheading{Helper classes and data structures
}
1305 The following classes and structs are defined in dbtable.cpp/.h for use with the wxDbTable class.
1306 \begin{itemize
}\itemsep=
0pt
1307 \item \helpref{wxDbColDef
}{wxdbcoldef
}
1308 \item \helpref{wxDbColDataPtr
}{wxdbcoldataptr
}
1309 \item \helpref{wxDbIdxDef
}{wxdbidxdef
}
1312 \wxheading{Constants
}
1315 wxDB_DEFAULT_CURSOR Index number of the cursor that each table will use
1318 wxDB_QUERY_ONLY Used to indicate whether a table that is opened is
1319 for query only, or if insert/update/deletes will
1320 be performed on the table. Less overhead (cursors
1321 and memory) are allocated for query only tables, plus
1322 read access times are faster with some datasources.
1324 wxDB_ROWID_LEN
[Oracle specific
] - Used when CanUpdateByRowID() is
1325 true. Optimizes updates so they are faster by
1326 updating on the Oracle-specific ROWID column rather
1327 than some other index.
1330 wxDB_DISABLE_VIEW Use to indicate when a database view should not be
1331 if a table is normally set up to use a view.
1332 [Currently unsupported.
]
1336 \wxheading{See also
}
1338 \helpref{wxDbTable
}{wxdbtable
}
1340 \latexignore{\rtfignore{\wxheading{Members
}}}
1342 \membersection{wxDbTable::wxDbTable
}\label{wxdbtableconstr
}
1344 \func{}{wxDbTable
}{\param{wxDb *
}{pwxDb
},
\param{const char *
}{tblName
},
\param{const int
}{nCols
},
\param{const char *
}{qryTblName =
0},
\param{bool
}{qryOnly = !wxDB_QUERY_ONLY
},
\param{const char *
}{tblPath=NULL
}}
1346 Default constructor.
1348 \wxheading{Parameters
}
1350 \docparam{pwxDb
}{Pointer to the wxDb instance to be used by this wxDbTable
1352 \docparam{tblName
}{The name of the table in the RDBMS.
}
1353 \docparam{nCols
}{The number of columns in the table. (Do NOT include the ROWID
1354 column in the count if using Oracle).
}
1355 \docparam{qryTblName
}{{\it OPTIONAL
}. The name of the table or view to base
1356 your queries on. This argument allows you to specify a table/view other than
1357 the base table for this object to base your queries on. This allows you to
1358 query on a view for example, but all of the INSERT, UPDATE and DELETES will
1359 still be performed on the base table for this wxDbTable object. Basing your
1360 queries on a view can provide a substantial performance increase in cases where
1361 your queries involve many tables with many joins. Default is
0 (NULL)
}
1362 \docparam{qryOnly
}{{\it OPTIONAL
}. Indicates whether the table will be
1363 accessible for query purposes only, or should the table create the necessary
1364 cursors to be able to insert, update, and delete data from the table.
1365 Default is !wxDB_QUERY_ONLY.
}
1366 \docparam{tblPath
}{{\it OPTIONAL
}. Some data sources (such as dBase)
1367 require a path to where the table is stored on the system. Default is NULL.
}
1369 \membersection{wxDbTable::wxDbTable
}\label{wxdbtabledestr
}
1371 \func{virtual
}{\destruct{wxDbTable
}}{}
1373 Virtual default destructor.
1376 \membersection{wxDbTable::BuildDeleteStmt
}\label{wxdbtablebuilddeletestmt
}
1378 \func{void
}{BuildDeleteStmt
}{\param{char *
}{pSqlStmt
},
\param{int
}{typeOfDel
},
\param{const char *
}{pWhereClause=
0}}
1380 Constructs the full SQL statement that can be used to delete all rows matching
1381 the criteria in the pWhereClause.
1383 \wxheading{Parameters
}
1385 \docparam{pSqlStmt
}{Pointer to storage for the SQL statement retrieved. To be
1386 sure you have adequate space allocated for the SQL statement, allocate
1387 DB_MAX_STATEMENT_LEN bytes.
}
1388 \docparam{typeOfDel
}{The type of delete statement being performed. Can be one
1389 of three values: DB_DEL_KEYFIELDS, DB_DEL_WHERE or DB_DEL_MATCHING
}
1390 \docparam{pWhereClause
}{{\it OPTIONAL
}. If the typeOfDel is DB_DEL_WHERE,
1391 then you must also pass in a SQL WHERE clause in this argument. Default
1396 This member function allows you to see what the SQL DELETE statement looks like
1397 that the ODBC class library builds. This can be used for debugging purposes if
1398 you are having problems executing your SQL statement.
1400 WHERE and FROM clauses specified in
\helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
1401 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
1405 \membersection{wxDbTable::BuildSelectStmt
}\label{wxdbtablebuildselectstmt
}
1407 \func{void
}{BuildSelectStmt
}{\param{char *
}{pSqlStmt
},
\param{int
}{typeOfSelect
},
\param{bool
}{distinct
}}
1409 Constructs the full SQL statement that can be used to select all rows matching
1410 the criteria in the pWhereClause. Internal to the wxDbTable class, this
1411 function is called whenever the function
\helpref{wxDbTable::Query
}{wxdbtablequery
}
1414 NOTE: Only the columns specified in
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
1415 statements are included in the list of columns returned by the SQL statement
1416 created by a call to this function.
1418 \wxheading{Parameters
}
1420 \docparam{pSqlStmt
}{Pointer to storage for the SQL statement retrieved. To be
1421 sure you have adequate space allocated for the SQL statement, allocate
1422 DB_MAX_STATEMENT_LEN bytes.
}
1423 \docparam{typeOfSelect
}{The type of select statement being performed. Can be
1424 one of four values: DB_SELECT_KEYFIELDS, DB_SELECT_WHERE, DB_SELECT_MATCHING
1425 or DB_SELECT_STATEMENT.
}
1426 \docparam{distinct
}{Whether to select distinct records only.
}
1430 This member function allows you to see what the SQL SELECT statement looks like
1431 that the ODBC class library builds. This can be used for debugging purposes if
1432 you are having problems executing your SQL statement.
1434 WHERE and FROM clauses specified in
\helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
1435 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
1439 \membersection{wxDbTable::BuildUpdateStmt
}\label{wxdbtablebuildupdatestmt
}
1441 \func{void
}{BuildSelectStmt
}{\param{char *
}{pSqlStmt
},
\param{int
}{typeOfUpd
},
\param{const char *
}{pWhereClause=
0}}
1443 Constructs the full SQL statement that can be used to update all rows matching
1444 the criteria in the pWhereClause.
1446 If typeOfUpd is DB_UPD_KEYFIELDS, then the current values in the bound columns
1447 are used to determine which row(s) in the table are to be updated. The
1448 exception to this is when a data source supports ROW IDs (Oracle). The ROW ID
1449 column is used for efficiency purposes when available.
1451 NOTE: Only the columns specified in
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
1452 statements are included in the list of columns updated by the SQL statement
1453 created by a call to this function. Any column definitions that were defined
1454 as being non-updateable will be excluded from the SQL UPDATE statement created
1457 \wxheading{Parameters
}
1459 \docparam{pSqlStmt
}{Pointer to storage for the SQL statement retrieved. To be
1460 sure you have adequate space allocated for the SQL statement, allocate
1461 DB_MAX_STATEMENT_LEN bytes.
}
1462 \docparam{typeOfUpd
}{The type of update statement being performed. Can be one
1463 of two values: DB_UPD_KEYFIELDS or DB_UPD_WHERE.
}
1464 \docparam{pWhereClause
}{{\it OPTIONAL
}. If the typeOfUpd is DB_UPD_WHERE,
1465 then you must also pass in a SQL WHERE clause in this argument. Default
1470 This member function allows you to see what the SQL UPDATE statement looks like
1471 that the ODBC class library builds. This can be used for debugging purposes if
1472 you are having problems executing your SQL statement.
1474 WHERE and FROM clauses specified in
\helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
1475 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
1479 \membersection{wxDbTable::BuildWhereStmt
}\label{wxdbtablebuildwherestmt
}
1481 \func{void
}{BuildSelectStmt
}{\param{char *
}{pWhereClause
},
\param{int
}{typeOfWhere
},
\param{const char *
}{qualTableName=
0},
\param{const char *
}{useLikeComparison=FALSE
}}
1483 Constructs the portion of a SQL statement which would follow the word 'WHERE'
1484 in the SQL statement to be passed to the data source. The returned string
1485 does NOT include the word 'WHERE'.
1487 \wxheading{Parameters
}
1489 \docparam{pWhereClause
}{Pointer to storage for the SQL statement retrieved.
1490 To be sure you have adequate space allocated for the SQL statement, allocate
1491 DB_MAX_STATEMENT_LEN bytes.
}
1492 \docparam{typeOfWhere
}{The type of where clause to generate. Can be one of
1493 two values: DB_WHERE_KEYFIELDS or DB_WHERE_MATCHING.
}
1494 \docparam{qualTableName
}{{\it OPTIONAL
}. Prepended to all base table
1495 column names. For use when a FROM clause has been specified with the
1496 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
},
1497 to clarify which table a column name reference belongs to. Default is
0
1499 \docparam{useLikeComparison
}{{\it OPTIONAL
}. Should the constructed WHERE
1500 clause utilize the LIKE comparison operator. If FALSE, then the '='
1501 operator is used. Default is FALSE.
}
1505 This member function allows you to see what the SQL WHERE clause looks like
1506 that the ODBC class library builds. This can be used for debugging purposes
1507 if you are having problems executing your SQL statements.
1509 If using 'typeOfWhere' set to DB_WHERE_MATCHING, any bound columns currently
1510 containing a NULL value are not included in the WHERE clause's list of
1511 columns to use in the comparison.
1514 \membersection{wxDbTable::CanSelectForUpdate
}\label{wxdbtablecanselectforupdate
}
1516 \func{bool
}{CanSelectForUpdate
}{\void}
1518 Use this function to determine if the data source supports SELECT ... FOR UPDATE.
1519 When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement,
1520 all records retrieved from the query are locked.
1524 Not all data sources support the "FOR UPDATE" clause, so you must use this
1525 member function to determine if the data source currently connected to supports
1526 this behavior or not before trying to select using "FOR UPDATE".
1529 \membersection{wxDbTable::CanUpdateByROWID
}\label{wxdbtablecanupdatebyrowid
}
1531 \func{bool
}{CanUpdateByROWID
}{\void}
1533 CURRENTLY ONLY POSSIBLE IF USING ORACLE.
1535 --- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV
1 2000 - gt
1537 Every Oracle table has a hidden column named ROWID. This is a pointer to the
1538 physical location of the record in the data store and allows for very fast
1539 updates and deletes. The key is to retrieve this ROWID during your query so
1540 it is available during an update or delete operation.
1542 This is always handled by the class library except in the case of
1543 QueryBySqlStatement(). Since you are passing in the SQL SELECT statement,
1544 it is up to you to include the ROWID column in your query. If you do not,
1545 the application will still work, but may not be as optimized. The ROWID is
1546 always the last column in the column list in your SQL SELECT statement.
1547 The ROWID is not a column in the normal sense and should not be considered
1548 part of the column definitions for the wxDbTable object.
1552 The decision to include the ROWID in your SQL SELECT statement must be
1553 deferred until runtime since it depends on whether you are connected
1554 to an Oracle data source or not.
1559 // Incomplete code sample
1562 if (parts.CanUpdByROWID())
1564 // Note that the ROWID column must always be the last column selected
1565 sqlStmt = "SELECT PART_NO, PART_DESC, ROWID" FROM PARTS";
1568 sqlStmt = "SELECT PART_NO, PART_DESC" FROM PARTS";
1572 \membersection{wxDbTable::ClearMemberVars
}\label{wxdbtableclearmembervars
}
1574 \func{void
}{ClearMemberVars
}{\void}
1576 Initializes all of the bound columns of the wxDbTable instance to zero.
1577 In the case of a string, zero is copied to the first byte of the string.
1581 This is useful before calling
\helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
1582 \helpref{wxDbTable::DeleteMatching
}{wxdbtabledeletematching
} since these
1583 functions build their WHERE clauses from non-zero columns. To call either
1584 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
1585 \helpref{wxDbTable::DeleteMatching
}{wxdbtabledeletematching
} use this sequence:
1588 1) ClearMemberVars()
1589 2) Assign columns values you wish to match on
1590 3) Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
1593 \membersection{wxDbTable::CloseCursor
}\label{wxdbtableclosecursor
}
1595 \func{bool
}{CloseCursor
}{\param{HSTMT
}{cursor
}}
1597 Closes the specified cursor associated with the wxDbTable object.
1599 \wxheading{Parameters
}
1601 \docparam{cursor
}{The cursor to be closed.
}
1605 Typically handled internally by the ODBC class library, but may be used by the
1606 programmer if desired.
1609 \membersection{wxDbTable::Count
}\label{wxdbtablecount
}
1611 \func{ULONG
}{Count
}{\param{const char *
}{args="*"
}}
1613 Returns the number of records which would be in the result set using the
1614 current query parameters specified in the WHERE and FROM clauses.
1616 \wxheading{Parameters
}
1618 \docparam{args
}{{\it OPTIONAL
}. This arguement allows the use of the
1619 DISTINCT keyword against a column name to cause the returned count to
1620 only indicate the number of rows in the result set that have a unique
1621 value in the specified column. An example is shown below. Default is "*",
1622 meaning a count of the total number of rows is returned, regardless of
1627 This function can be called before or after an actual query to obtain the
1628 count of records in the result set. Count() uses its own cursor, so result
1629 set cursor positioning is not affected by calls to Count().
1637 FIRST_NAME LAST_NAME
1638 ----------- ----------
1644 // Incomplete code sample
1647 users.SetWhereClause("");
1649 // This Count() will return
4, as there are four users listed above
1650 // that match the query parameters
1651 totalNumberOfUsers = users.Count();
1653 // This Count() will return
3, as there are only
3 unique first names
1654 // in the table above - John, Richard, Michael.
1655 totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
1659 \membersection{wxDbTable::CreateIndex
}\label{wxdbtablecreateindex
}
1661 \func{bool
}{CreateIndex
}{\param{const char *
}{idxName
},
\param{bool
}{unique
},
\param{int
}{noIdxCols
},
\param{wxDbIdxDef *
}{pIdxDefs
},
\param{bool
}{attemptDrop=TRUE
}}
1663 This member function allows you to create secondary (non primary) indexes on
1664 your tables. You first create your table, normally specifying a primary
1665 index, and then create any secondary indexes on the table. Indexes in
1666 relational model are not required. You do not need indexes to look up records
1667 in a table or to join two tables together. In the relational model, indexes,
1668 if available, provide a quicker means to look up data in a table. To enjoy
1669 the performance benefits of indexes, the indexes must be defined on the
1670 appropriate columns and your SQL code must be written in such a way as to
1671 take advantage of those indexes.
1673 \wxheading{Parameters
}
1675 \docparam{idxName
}{Name of the Index. Name must be unique within the table space of the datasource.
}
1676 \docparam{unique
}{Indicates if this index is unique.
}
1677 \docparam{noIdxCols
}{Number of columns in the index.
}
1678 \docparam{pIdxDefs
}{A pointer to an array wxDbIdxDef structures.
}
1679 \docparam{attemptDrop
}{{\it OPTIONAL
}. Indicates if the function should try
1680 to execute a
\helpref{wxDbTable::DropIndex
}{wxdbtabledropindex
} on the index
1681 name provided before trying to create the index name. Default is TRUE.
}
1685 The first parameter, index name, must be unique and should be given a
1686 meaningful name. Common practice is to include the table name as a prefix
1687 in the index name (e.g. PARTS_IDX1). This will allow you to easily view all
1688 of the indexes defined for a given table grouped together alphabetically.
1690 The second parameter indicates if the index is unique or not. Uniqueness
1691 is enforced at the RDBMS level controlling whether duplicates cannot be
1692 inserted into the table for unique indices.
1694 In the third parameter, specify how many columns are in your index. This
1695 number must match the number of columns defined in the 'pIdxDefs' parameter.
1697 The fourth parameter specifies which columns make up the index using the
1698 wxDbIdxDef structure. For each column in the index, you must specify two
1699 things, the column name and the sort order (ascending / descending). See
1700 the example below to see how to build and pass in the wxDbIdxDef structure.
1702 The fifth parameter is provided as many datasources will not automatically
1703 overwrite existing indexes with the same name. They require that the
1704 existing index must be dropped first, so this is the default behavior.
1706 Some datasources (MySQL, and possibly others) require columns which are to be
1707 part of an index to be defined as NOT NULL. When this function is called, if
1708 a column is not defined to be NOT NULL, this function will modify the column
1709 definition to change the column to be NOT NULL.
1711 PostGres is unable to handle index definitions which specify whether the index
1712 is ascending or descending, and defaults to the system default when the index
1715 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
1716 after executing this function.
1721 // Create a secondary index on the PARTS table
1722 wxDbIdxDef idxDef
[2]; //
2 columns make up the index
1724 strcpy(idxDef
[0].ColName, "PART_DESC"); // Column
1
1725 idxDef
[0].Ascending = TRUE;
1727 strcpy(idxDef
[1].ColName, "SERIAL_NO"); // Column
2
1728 idxDef
[1].Ascending = FALSE;
1730 // Create a name for the index based on the table's name
1732 indexName.sprintf("
%s_IDX1",parts->GetTableName());
1733 parts->CreateIndex(indexName.c_str(), TRUE,
2, idxDef);
1737 \membersection{wxDbTable::CreateTable
}\label{wxdbtablecreatetable
}
1739 \func{bool
}{CreateTable
}{\param{bool
}{attemptDrop=TRUE
}}
1741 Creates a table based on the definitions previously defined for this
1744 \wxheading{Parameters
}
1746 \docparam{attemptDrop
}{{\it OPTIONAL
}. Default is TRUE.
}
1750 This function creates the table and primary index (if any) in the table space
1751 associated with the connected data source. The owner of these objects will
1752 be the user id that was given when
\helpref{wxDb::Open
}{wxdbopen
} was called. The objects will
1753 be created in the default schema for that user.
1755 In your derived wxDbTable object constructor, the columns and primary index
1756 of the table are described through the wxDbColDef structure.
1757 \helpref{wxDbTable::CreateTable
}{wxdbtablecreatetable
} uses this information to create the table and to add
1758 the primary index. See
\helpref{wxDbTable
}{wxdbtable
} ctor and wxDbColDef
1759 description for additional information on describing the columns of the table.
1761 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
1762 after executing this function.
1765 \membersection{wxDbTable::DB_STATUS
}\label{wxdbtabledbstatus
}
1767 \func{bool
}{DB_STATUS
}{\void}
1769 Accessor function that returns the wxDb private member variable DB_STATUS for
1770 the database connection used by this instance of wxDbTable.
1773 \membersection{wxDbTable::Delete
}\label{wxdbtabledelete
}
1775 \func{bool
}{Delete
}{\void}
1777 Deletes the current record from the data source.
1781 Use
\helpref{wxDbTable::GetFirst
}{wxdbtablegetfirst
},
\helpref{wxDbTable::GetLast
}{wxdbtablegetlast
},
1782 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
} or
1783 \helpref{wxDbTable::GetPrev
}{wxdbtablegetprev
} to position the cursor to
1784 a valid record. Once positioned on a record, call this function to delete
1785 the row from the table.
1787 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
1788 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
1789 this function to commit or rollback the deletion.
1791 NOTE: Most datasources have a limited size "rollback" segment. This means
1792 that it is only possible to insert/update/delete a finite number of rows
1793 without performing a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
1794 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
}. Size of the rollback
1795 segment varies from database to database, and is user configurable in
1796 most databases. Therefore it is usually best to try to perform a commit
1797 or rollback at relatively small intervals when processing a larger number
1798 of actions that insert/update/delete rows in a table.
1801 \membersection{wxDbTable::DeleteCursor
}\label{wxdbtabledeletecursor
}
1803 \func{bool
}{DeleteCursor
}{\param{HSTMT *
}{hstmtDel
}}
1805 Allows a program to delete a cursor.
1807 \wxheading{Parameters
}
1809 \docparam{hstmtDel
}{Handle of the cursor to delete.
}
1813 For default cursors associated with the instance of wxDbTable, it is not
1814 necessary to specifically delete the cursors. This is automatically done
1815 in the wxDbTable destructor.
1817 NOTE: If the cursor could not be deleted for some reason, an error is logged
1818 indicating the reason. Even if the cursor could not be deleted, the HSTMT
1819 that is passed in is deleted, and the pointer is set to NULL.
1822 \membersection{wxDbTable::DeleteMatching
}\label{wxdbtabledeletematching
}
1824 \func{bool
}{DeleteMatching
}{\void}
1826 This member function allows you to delete records from your wxDbTable object
1827 by specifying the data to match in the columns to match on.
1831 To delete all users with a first name of "JOHN", do the following:
1834 1) Clear all "columns" using
\helpref{wxDbTable::ClearMemberVars
}{wxdbtableclearmembervars
}.
1835 2) Set the FIRST_NAME column equal to "JOHN".
1836 3) Call
\helpref{wxDbTable::DeleteMatching
}{wxdbtabledeletematching
}.
1839 The WHERE clause is built by the ODBC class library based on all non-zero
1840 columns. This allows deletion of records by matching on any column(s)
1841 in your wxDbTable instance, without having to write the SQL WHERE clause.
1843 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
1844 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
1845 this function to commit or rollback the deletion.
1847 NOTE: Row(s) should be locked before deleting them to make sure they are
1848 not already in use. This can be achieved by calling
\helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
},
1849 and then scrolling through the records locking each as you go. After the
1850 row(s) have been successfully locked, call this function.
1852 NOTE: Most datasources have a limited size "rollback" segment. This means
1853 that it is only possible to insert/update/delete a finite number of rows
1854 without performing a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
1855 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
}. Size of the rollback
1856 segment varies from database to database, and is user configurable in
1857 most databases. Therefore it is usually best to try to perform a commit
1858 or rollback at relatively small intervals when processing a larger number
1859 of actions that insert/update/delete rows in a table.
1865 // Incomplete code sample to delete all users with a first name
1867 users.ClearMemberVars();
1868 strcpy(users.FirstName,"JOHN");
1869 users.DeleteMatching();
1873 \membersection{wxDbTable::DeleteWhere
}\label{wxdbtabledeletewhere
}
1875 \func{bool
}{DeleteWhere
}{\param{const char *
}{pWhereClause
}}
1877 Deletes all rows from the table which match the criteria specified in the
1878 WHERE clause that is passed in as the sole parameter.
1880 \wxheading{Parameters
}
1882 \docparam{pWhereClause
}{SQL WHERE clause. This WHERE clause determines which
1883 records will be deleted from the table interfaced through the wxDbTable
1884 instance. The WHERE clause passed in must be compliant with the SQL
92
1885 grammar. Do not include the keyword 'WHERE'
1890 This is the most powerful form of the wxDbTable delete functions. This
1891 function gives access to the full power of SQL. This function can be used
1892 to delete records by passing a valid SQL WHERE clause. Sophisticated
1893 deletions can be performed based on multiple criteria using the full
1894 functionality of the SQL language.
1896 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} must be called after use of
1897 this function to commit the deletions.
1899 Note: This function is limited to deleting records from the table associated
1900 with this wxDbTable object only. Deletions on joined tables is not possible.
1902 NOTE: Most datasources have a limited size "rollback" segment. This means
1903 that it is only possible to insert/update/delete a finite number of rows
1904 without performing a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
1905 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
}. Size of the rollback
1906 segment varies from database to database, and is user configurable in
1907 most databases. Therefore it is usually best to try to perform a commit
1908 or rollback at relatively small intervals when processing a larger number
1909 of actions that insert/update/delete rows in a table.
1914 // Delete parts
1 thru
10 from containers 'X', 'Y' and 'Z' that
1915 // are magenta in
color
1916 parts.DeleteWhere("(PART_NUMBER BETWEEN
1 AND
10) AND \
1917 CONTAINER IN ('X', 'Y', 'Z') AND \
1918 UPPER(COLOR) = 'MAGENTA'");
1922 \membersection{wxDbTable::DropIndex
}\label{wxdbtabledropindex
}
1924 \func{bool
}{DropIndex
}{\param{const char *
}{idxName
}}
1926 Allows an index on the associated table to be dropped (deleted) if the user
1927 login has sufficient privileges to do so.
1929 \wxheading{Parameters
}
1931 \docparam{idxName
}{Name of the index to be dropped.
}
1935 If the index specified in the 'idxName' parameter does not exist, an error
1936 will be logged, and the function will return a result of FALSE.
1938 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
1939 after executing this function.
1942 \membersection{wxDbTable::DropTable
}\label{wxdbtabledroptable
}
1944 \func{bool
}{DropTable
}{\void}
1946 Deletes the associated table if the user has sufficient privileges to do so.
1950 This function returns TRUE if the table does not exist, but only for
1951 supported databases (see
\helpref{wxDb::Dbms
}{wxdbdbms
}). If a datasource
1952 is not specifically supported, and this function is called, the function
1955 Some datasources/ODBC drivers will delete any indexes associated with the
1956 table automatically, and others may not. Check the documentation for your
1957 database to determine the behavior.
1959 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
1960 after executing this function.
1963 \membersection{wxDbTable::From
}\label{wxdbtablefrom
}
1965 \func{const char *
}{From
}{}
1966 \func{void
}{From
}{\param{const wxString &
}{From
}}
1968 Accessor function for the private class member wxDbTable::from. Can be used
1969 as a synonym for
\helpref{wxDbTable::GetFromClause
}{wxdbtablegetfromclause
}
1970 (the first form of this function) or
1971 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} (the second form
1974 \wxheading{Parameters
}
1976 \docparam{From
}{A comma separated list of table names that are to be outer
1977 joined with the base table's columns so that the joined table's columns
1978 may be returned in the result set or used as a portion of a comparison with
1979 the base table's columns. NOTE that the base tables name must NOT be included
1980 in the FROM clause, as it is automatically included by the wxDbTable class
1981 in constructing query statements.
}
1983 \wxheading{Return value
}
1985 The first form of this function returns the current value of the wxDbTable
1986 member variable ::from.
1988 The second form of the function has no return value.
1990 \wxheading{See also
}
1992 \helpref{wxDbTable::GetFromClause
}{wxdbtablegetfromclause
},
1993 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}
1996 \membersection{wxDbTable::GetColDefs
}\label{wxdbtablegetcoldefs
}
1998 \func{wxDbColDef *
}{GetColDefs
}{}
2000 Accessor function that returns a pointer to the array of column definitions
2001 that are bound to the columns that this wxDbTable instance is associated
2004 To determine the number of elements pointed to by the returned
2005 \helpref{wxDbColDef
}{wxdbcoldef
} pointer, use the
2006 \helpref{wxDbTable::GetNumberOfColumns
}{wxdbtablegetnumberofcolumns
} function.
2010 These column definitions must not be manually redefined after they have been
2014 \membersection{wxDbTable::GetCursor
}\label{wxdbtablegetcursor
}
2016 \func{HSTMT
}{GetCursor
}{\void}
2018 Returns the HSTMT value of the current cursor for this wxDbTable object.
2022 This function is typically used just before changing to use a different cursor
2023 so that after the program is finished using the other cursor, the current
2024 cursor can be set back to being the cursor in use.
2026 \wxheading{See also
}
2028 \helpref{wxDbTable::SetCursor
}{wxdbtablesetcursor
},
\helpref{wxDbTable::GetNewCursor
}{wxdbtablegetnewcursor
}
2031 \membersection{wxDbTable::GetDb
}\label{wxdbtablegetdb
}
2033 \func{wxDb *
}{GetDb
}{}
2035 Accessor function for the private member variable pDb which is a pointer to
2036 the datasource connection that this wxDbTable instance uses.
2039 \membersection{wxDbTable::GetFirst
}\label{wxdbtablegetfirst
}
2041 \func{bool
}{GetFirst
}{\void}
2043 Retrieves the FIRST row in the record set as defined by the current query.
2044 Before retrieving records, a query must be performed using
2045 \helpref{wxDbTable::Query
}{wxdbtablequery
},
2046 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2047 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2048 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2052 This function can only be used if the datasource connection used by the
2053 wxDbTable instance was created with FwdOnlyCursors set to FALSE. If the
2054 connection does not allow backward scrolling cursors, this function will
2055 return FALSE, and the data contained in the bound columns will be undefined.
2057 \wxheading{See also
}
2059 \helpref{wxDb::FwdOnlyCursors
}{wxdbfwdonlycursors
}
2062 \membersection{wxDbTable::GetFromClause
}\label{wxdbtablegetfromclause
}
2064 \func{const char *
}{GetFromClause
}{}
2066 Accessor function that returns the current FROM setting assigned with the
2067 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}.
2069 \wxheading{See also
}
2071 \helpref{wxDbTable::From
}{wxdbtablefrom
}
2074 \membersection{wxDbTable::GetLast
}\label{wxdbtablegetlast
}
2076 \func{bool
}{GetLast
}{\void}
2078 Retrieves the LAST row in the record set as defined by the current query.
2079 Before retrieving records, a query must be performed using
2080 \helpref{wxDbTable::Query
}{wxdbtablequery
},
2081 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2082 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2083 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2087 This function can only be used if the datasource connection used by the
2088 wxDbTable instance was created with FwdOnlyCursors set to FALSE. If the
2089 connection does not allow backward scrolling cursors, this function will
2090 return FALSE, and the data contained in the bound columns will be undefined.
2092 \wxheading{See also
}
2094 \helpref{wxDb::FwdOnlyCursors
}{wxdbfwdonlycursors
}
2097 \membersection{wxDbTable::GetNewCursor
}\label{wxdbtablegetnewcursor
}
2099 \func{HSTMT *
}{GetNewCursor
}{\param{bool
}{setCursor=FALSE
},
\param{bool
}{bindColumns=TRUE
}}
2102 % George: @@@@@@@@STILL TO DO
2105 \wxheading{Parameters
}
2107 \docparam{setCursor
}{{\it OPTIONAL
}. Default is FALSE.
}
2108 \docparam{bindColumns
}{{\it OPTIONAL
}. Default is TRUE.
}
2113 \membersection{wxDbTable::GetNext
}\label{wxdbtablegetnext
}
2115 \func{bool
}{GetNext
}{\void}
2117 Retrieves the NEXT row in the record set after the current cursor position
2118 as defined by the current query. Before retrieving records, a query must be
2119 performed using
\helpref{wxDbTable::Query
}{wxdbtablequery
},
2120 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2121 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2122 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2124 \wxheading{Return value
}
2126 This function returns FALSE when the current cursor has reached the end of
2127 the result set. When FALSE is returned, data in the bound columns is
2130 \wxheading{See also
}
2131 \helpref{wxDbTable::++
}{wxdbtableplusplus
}
2134 \membersection{wxDbTable::GetNumberOfColumns
}\label{wxdbtablegetnumberofcolumns
}
2136 \func{bool
}{GetNumberOfColumns
}{}
2138 Accessor function that returns the number of columns that are statically
2139 bound for access by the wxDbTable instance.
2142 \membersection{wxDbTable::GetOrderByClause
}\label{wxdbtablegetorderbyclause
}
2144 \func{const char *
}{GetOrderByClause
}{}
2146 Accessor function that returns the current ORDER BY setting assigned with
2147 the
\helpref{wxDbTable::SetOrderByClause
}{wxdbtablesetorderbyclause
}.
2149 \wxheading{See also
}
2151 \helpref{wxDbTable::OrderBy
}{wxdbtableorderby
}
2154 \membersection{wxDbTable::GetPrev
}\label{wxdbtablegetprev
}
2156 \func{bool
}{GetPrev
}{\void}
2158 Retrieves the PREVIOUS row in the record set before the current cursor
2159 position as defined by the current query. Before retrieving records, a
2160 query must be performed using
\helpref{wxDbTable::Query
}{wxdbtablequery
},
2161 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2162 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2163 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2165 \wxheading{Return value
}
2167 This function returns FALSE when the current cursor has reached the beginning
2168 of the result set and there are now other rows prior to the cursors current
2169 position. When FALSE is returned, data in the bound columns is undefined.
2173 This function can only be used if the datasource connection used by the
2174 wxDbTable instance was created with FwdOnlyCursors set to FALSE. If the
2175 connection does not allow backward scrolling cursors, this function will
2176 return FALSE, and the data contained in the bound columns will be undefined.
2178 \wxheading{See also
}
2180 \helpref{wxDb::FwdOnlyCursors
}{wxdbfwdonlycursors
},
2181 \helpref{wxDbTable::--
}{wxdbtableminusminus
}
2184 \membersection{wxDbTable::GetQueryTableName
}\label{wxdbtablegetquerytablename
}
2186 \func{const char *
}{GetQueryTableName
}{}
2188 Accessor function that returns the name of the table/view that was indicated
2189 as being the table/view to query against when this wxDbTable instance was
2192 \wxheading{See also
}
2194 \helpref{wxDbTable constructor
}{wxdbtableconstr
}
2197 \membersection{wxDbTable::GetRowNum
}\label{wxdbtablegetrownum
}
2199 \func{UWORD
}{GetRowNum
}{\void}
2201 Returns the ODBC row number for performing positioned updates and deletes.
2205 This function is not being used within the ODBC class library and may be a
2206 candidate for removal if no use is found for it.
2209 \membersection{wxDbTable::GetTableName
}\label{wxdbtablegettablename
}
2211 \func{const char *
}{GetTableName
}{}
2213 Accessor function that returns the name of the table that was indicated
2214 as being the table that this wxDbTable instance was associated with.
2217 \membersection{wxDbTable::GetTablePath
}\label{wxdbtablegettablepath
}
2219 \func{const char *
}{GetTablePath
}{}
2221 Accessor function that returns the path to the data table that was indicated
2222 during creation of this wxDbTable instance.
2226 Currently only applicable to dBase and MS-Access datasources.
2229 \membersection{wxDbTable::GetWhereClause
}\label{wxdbtablegetwhereclause
}
2231 \func{const char *
}{GetWhereClause
}{}
2233 Accessor function that returns the current WHERE setting assigned with the
2234 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2236 \wxheading{See also
}
2238 \helpref{wxDbTable::Where
}{wxdbtablewhere
}
2241 \membersection{wxDbTable::Insert
}\label{wxdbtableinsert
}
2243 \func{int
}{Insert
}{\void}
2245 Inserts a new record into the table being referenced by this wxDbTable
2246 instance. The values in the member variables of the wxDbTable instance are
2247 inserted into the columns of the new row in the database
2249 \wxheading{Return value
}
2252 DB_SUCCESS Record inserted successfully (value =
1)
2254 DB_FAILURE Insert failed (value =
0)
2256 DB_ERR_INTEGRITY_CONSTRAINT_VIOL
2257 The insert failed due to an integrity
2258 constraint violation (duplicate non-unique
2259 index entry) is attempted.
2264 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
2265 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
2266 this function to commit or rollback the insertion.
2271 // Incomplete code snippet
2272 strcpy(parts->PartName, "
10");
2273 strcpy(parts->PartDesc, "Part
#10");
2275 RETCODE retcode = parts.Insert();
2279 parts->GetDb()->CommitTrans();
2281 case DB_ERR_INTEGRITY_CONSTRAINT_VIOL:
2282 // Current data would result in a duplicate key
2283 // on one or more indexes that do not allow duplicates
2284 parts->GetDb()->RollbackTrans();
2287 // Insert failed for some unexpected reason
2288 parts->GetDb()->RollbackTrans();
2294 \membersection{wxDbTable::IsColNull
}\label{wxdbtableiscolnull
}
2296 \func{bool
}{IsColNull
}{\param{int
}{colNo
}}
2298 Used primarily in the ODBC class library to determine if a column is equal
2299 to "NULL". Works for all data types supported by the ODBC class library.
2301 \wxheading{Parameters
}
2303 \docparam{colNo
}{The column number of the bound column as defined by the
2304 \helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
2305 calls which defined the columns accesible to this wxDbTable instance.
}
2309 NULL column support is currently not fully implemented as of wxWindows
2.4
2312 \membersection{wxDbTable::IsCursorClosedOnCommit
}\label{wxdbtableiscursorclosedoncommit
}
2314 \func{bool
}{IsCursorClosedOnCommit
}{\void}
2316 Accessor function to return information collected during the opening of the
2317 datasource connection that is used by this wxDbTable instance.
2319 \wxheading{Return value
}
2321 Returns TRUE if the cursor associated with this wxDbTable object is closed
2322 after a commit or rollback operation. Returns FALSE otherwise.
2325 \membersection{wxDbTable::IsQueryOnly
}\label{wxdbtableisqueryonly
}
2327 \func{bool
}{IsQueryOnly
}{}
2329 Accessor function that returns a value indicating if this wxDbTable instance
2330 was created to allow only queries to be performed on the bound columns. If
2331 this function returns TRUE, then no actions may be performed using this
2332 wxDbTable instance that would modify (insert/delete/update) the table's data.
2335 \membersection{wxDbTable::Open
}\label{wxdbtableopen
}
2337 \func{bool
}{Open
}{\void}
2339 Every wxDbTable instance must be opened before it can be used. This function
2340 checks for the existence of the requested table, binds columns to the
2341 internal cursors needed (insert/update/select) and constructs the insert
2342 statement that is used for inserting data to the columns of a new row in
2347 If the function returns a FALSE value due to the table not existing, a log
2348 entry is recorded for the datasource connection indicating the problem
2349 that was detected when checking for table existence. Note that it is usually
2350 best for the calling routine to check for the existence of the table and for
2351 sufficent user privileges to access the table in the mode (wxDB_QUERY_ONLY or
2352 !wxDB_QUERY_ONLY) before trying to open the table for the best possible
2353 return results as to why a table cannot be opened.
2355 \wxheading{See also
}
2357 \helpref{wxDb::TableExists
}{wxdbtableexists
},
\helpref{wxDb::TablePrivileges
}{wxdbtableprivileges
}
2360 \membersection{wxDbTable::OrderBy
}\label{wxdbtableorderby
}
2362 \func{const char *
}{OrderBy
}{}
2363 \func{void
}{OrderBy
}{\param{const wxString &
}{OrderBy
}}
2365 Accessor function for the private class member wxDbTable::orderBy. Can be
2366 used as a synonym for
\helpref{wxDbTable::GetOrderByClause
}{wxdbtablegetorderbyclause
}
2367 (the first form of this function) or
\helpref{wxDbTable::SetOrderByClause
}{wxdbtablesetorderbyclause
}
2368 (the second form of this function).
2370 \wxheading{Parameters
}
2372 \docparam{OrderBy
}{A comma separated list of column names that indicate the
2373 alphabetized sorting sequence that the result set is to be returned in. If
2374 a FROM clause has also been specified, each column name specified in the
2375 ORDER BY clause should be prefaced with the table name to which the column
2376 belongs using DOT notation (TABLE.COLUMN).
}
2378 \wxheading{Return value
}
2380 The first form of this function returns the current value of the wxDbTable
2381 member variable ::orderBy.
2383 The second form of the function has no return value.
2385 \wxheading{See also
}
2387 \helpref{wxDbTable::GetOrderByClause
}{wxdbtablegetorderbyclause
},
2388 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}
2391 \membersection{wxDbTable::Query
}\label{wxdbtablequery
}
2393 \func{virtual bool
}{Query
}{\param{bool
}{forUpdate=FALSE
},
\param{bool
}{distinct=FALSE
}}
2395 \wxheading{Parameters
}
2397 \docparam{forUpdate
}{{\it OPTIONAL
}. Gives you the option of locking records
2398 as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
2399 the FOR UPDATE clause, this argument is ignored. See
2400 \helpref{wxDbTable::CanSelectForUpdate
}{wxdbtablecanselectforupdate
} for
2401 additional information regarding this argument. Default is FALSE.
}
2402 \docparam{distinct
}{{\it OPTIONAL
}. Allows selection of only distinct values
2403 from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
2404 applies to all columns returned in the result set, not individual columns.
2409 This function queries records from the datasource based on the three
2410 wxDbTable members: "where", "orderBy", and "from". Use
2411 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
} to filter on
2412 records to be retrieved (e.g. All users with a first name of "JOHN").
2413 Use
\helpref{wxDbTable::SetOrderByClause
}{wxdbtablesetorderbyclause
} to
2414 change the sequence in which records are returned in the result set from
2415 the datasource (e.g. Ordered by LAST_NAME). Use
2416 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} to allow outer
2417 joining of the base table (the one being associated with this instance of
2418 wxDbTable) with other tables which share a related field.
2420 After each of these clauses are set/cleared, call wxDbTable::Query() to
2421 fetch the result set from the datasource.
2423 This scheme has an advantage if you have to requery your record set
2424 frequently in that you only have to set your WHERE, ORDER BY, and FROM
2425 clauses once. Then to refresh the record set, simply call wxDbTable::Query()
2426 as frequently as needed.
2428 Note that repeated calls to wxDbTable::Query() may tax the database
2429 server and make your application sluggish if done too frequently or
2432 The base table name is automatically prepended to the base column names in
2433 the event that the FROM clause has been set (is non-null) using
2434 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}.
2436 The cursor for the result set is positioned
{\it before
} the first record in
2437 the record set after the query. To retrieve the first record, call
2438 \helpref{wxDbTable::GetFirst
}{wxdbtablegetfirst
} or
2439 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}. Typically, no data from the
2440 result set is returned to the client driver until a request to such as
2441 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
} is performed, so network
2442 traffic and database load are not overwhelmed transmitting data until the
2443 data is actually requested by the client. This behavior is solely dependent
2444 on the ODBC driver though, so refer to the ODBC driver's reference material
2445 for information on its behaviors.
2447 The wxDbTable::Query() function is defined as "virtual" so that it may be
2448 overridden for application specific purposes.
2450 \normalbox{Be sure and set the wxDbTable's "where", "orderBy", and "from"
2451 member variables to "" if they are not being used in the query. Otherwise,
2452 the results returned may have unexpected results (or no results) due to
2453 improper or incorrect query parameters constructed from the uninitialized
2459 // Incomplete code sample
2460 parts->SetWhereClause("DESCRIPTION = 'FOOD'");
2461 parts->SetOrderByClause("EXPIRATION_DATE");
2462 parts->SetFromClause("");
2463 // Query the records based on the where, orderBy and from clauses
2466 // Display all records queried
2467 while(parts->GetNext())
2468 dispPart(parts); // user defined function
2472 \membersection{wxDbTable::QueryBySqlStmt
}\label{wxdbtablequerybysqlstmt
}
2474 \func{bool
}{QueryBySqlStmt
}{\param{const char *
}{pSqlStmt
}}
2476 Performs a query against the datasource by accepting and passing verbatim the
2477 SQL SELECT statement passed to the function.
2479 \wxheading{Parameters
}
2481 \docparam{pSqlStmt
}{A pointer to the SQL SELECT statement to be executed.
}
2485 This is the most powerful form of the query functions available. This member
2486 function allows a programmer to write their own custom SQL SELECT statement
2487 for requesting data from the data source. This gives the programmer access
2488 to the full power of SQL for performing operations such as scalar functions,
2489 aggregate functions, table joins, and sub-queries, as well as datasource
2490 specific function calls.
2492 The requirements of the SELECT statement are the following:
2495 1. Must return the correct number of columns. In the derived wxDbTable
2496 constructor, it is specified how many columns are in the wxDbTable
2497 object. The SELECT statement must return exactly that many columns.
2499 2. The columns must be returned in the same sequence as specified
2500 when defining the bounds columns using wxDbTable::SetColDefs(), and
2501 the columns returned must be of the proper data type. For example,
2502 if column
3 is defined in the wxDbTable bound column definitions to be a float,
2503 the SELECT statement must return a float for column
3 (e.g.
2504 PRICE *
1.10 to increase the price by
10%).
2506 3. The ROWID can be included in your SELECT statement as the last column
2507 selected, if the datasource supports it. Use wxDbTable::CanUpdByROWID()
2508 to determine if the ROWID can be selected from the datasource. If it
2509 can, much better performance can be achieved on updates and deletes
2510 by including the ROWID in the SELECT statement.
2513 Even though data can be selected from multiple tables in your select
2514 statement (joins), only the base table associated with this wxDbTable object
2515 is automatically updated through the ODBC class library. Data from multiple
2516 tables can be selected for display purposes however. Include columns in
2517 the wxDbTable object and mark them as non-updateable (See
2518 \helpref{wxDbColDef
}{wxdbcoldef
} for details). This way columns can be
2519 selected and displayed from other tables, but only the base table will be
2520 updated automatically through the
\helpref{wxDbTable::Update
}{wxdbtableupdate
}
2521 function. To update tables other than the base table, use the
2522 \helpref{wxDbTable::Update
}{wxdbtableupdate
} function passing a SQL statement.
2524 After this function has been called, the cursor is positioned before the
2525 first record in the record set. To retrieve the first record, call
2526 either
\helpref{wxDbTable::GetFirst
}{wxdbtablegetfirst
} or
2527 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}.
2532 // Incomplete code samples
2533 strcpy(sqlStmt, "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
2534 AND CONTAINER =
12");
2535 // Query the records using the SQL SELECT statement above
2536 parts->QueryBySqlStmt(sqlStmt);
2537 // Display all records queried
2538 while(parts->GetNext())
2541 Example SQL statements
2542 ----------------------
2544 // Table Join returning
3 columns
2545 SELECT part_no, part_desc, sd_name
2546 from parts, storage_devices
2547 where parts.storage_device_id = storage_devices.storage_device_id
2549 // Aggregate function returning total number of parts in container
99
2550 SELECT count
(*) from PARTS where container = 99
2552 // Order by clause; ROWID, scalar function
2553 SELECT part_no, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
2555 where warehouse = 10
2556 order by part_no desc // descending order
2560 where container in (select container
2561 from storage_devices
2562 where device_id = 12)
2566 \membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
2568 \func{virtual bool}{QueryMatching}{\param{bool }{forUpdate=FALSE}, \param{bool }{distinct=FALSE}}
2570 QueryMatching allows querying of records from the table associated with
2571 the wxDbTable object by matching "columns" to values.
2573 For example: To query the datasource for the row with a PART_NUMBER column
2574 value of "32", clear all column variables of the wxDbTable object, set the
2575 PartNumber variable that is bound to the PART_NUMBER column in the wxDbTable
2576 object to "32", and then call wxDbTable::QueryMatching().
2578 \wxheading{Parameters}
2580 \docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
2581 as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
2582 the FOR UPDATE clause, this argument is ignored. See
2583 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
2584 additional information regarding this argument. Default is FALSE.}
2585 \docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
2586 from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
2587 applies to all columns returned in the result set, not individual columns.
2592 The SQL WHERE clause is built by the ODBC class library based on all
2593 non-zero/non-NULL columns in your wxDbTable object. Matches can be on one,
2594 many or all of the wxDbTable's columns. The base table name is prepended
2595 to the column names in the event that the wxDbTable's FROM clause is non-null.
2597 This function cannot be used to perform queries which will check for
2598 columns that are 0 or NULL, as the automatically constructed WHERE clause
2599 only will contain comparisons on column member variables that are
2602 The primary difference between this function and \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields}
2603 is that this function can query on any column(s) in the wxDbTable object.
2604 Note however that this may not always be very efficient. Searching on
2605 non-indexed columns will always require a full table scan.
2607 The cursor is positioned before the first record in the record set after
2608 the query is performed. To retrieve the first record, the program must call
2609 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
2610 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
2615 // Incomplete code sample
2616 parts->ClearMemberVars(); // Set all columns to zero
2617 strcpy(parts->PartNumber,"32"); // Set columns to query on
2618 parts->OnHold = TRUE;
2619 parts->QueryMatching(); // Query
2620 // Display all records queried
2621 while(parts->GetNext())
2622 dispPart(parts); // Some application defined function
2626 \membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
2628 \func{bool}{QueryOnKeyFields}{\param{bool }{forUpdate=FALSE}, \param{bool }{distinct=FALSE}}
2630 QueryOnKeyFields provides an easy mechanism to query records in the table
2631 associated with the wxDbTable object by the primary index column(s). Simply
2632 assign the primary index column(s) values and then call this member function
2633 to retrieve the record.
2635 Note that since primary indexes are always unique, this function implicitly
2636 always returns a single record from the database. The base table name is
2637 prepended to the column names in the event that the wxDbTable's FROM clause
2640 \wxheading{Parameters}
2642 \docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
2643 as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
2644 the FOR UPDATE clause, this argument is ignored. See
2645 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
2646 additional information regarding this argument. Default is FALSE.}
2647 \docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
2648 from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
2649 applies to all columns returned in the result set, not individual columns.
2654 The cursor is positioned before the first record in the record set after
2655 the query is performed. To retrieve the first record, the program must call
2656 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
2657 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
2662 // Incomplete code sample
2663 strcpy(parts->PartNumber, "32");
2664 parts->QueryOnKeyFields();
2665 // Display all records queried
2666 while(parts->GetNext())
2667 dispPart(parts); // Some application defined function
2671 \membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
2673 \func{bool}{Refresh}{\void}
2675 Refreshes (re-reads into the bound columns) the current record for the
2676 current active cursor of the wxDbTable object.
2678 The cursor position and result set are unaffected by calls to this function.
2679 (The one exception is in the case where the record to be refreshed has been
2680 deleted by some other user or transaction since it was originally retrieved
2681 as part of the result set. For most datasources, the default behavior in
2682 this situation is to return the value that was originally queried for the
2683 result set, even though it has been deleted from the database. But this is
2684 datasource dependent, and should be tested before relying on this behavior.)
2688 This routine is only guaranteed to work if the table has a unique primary
2689 index defined for it. Otherwise, more than one record may be fetched and
2690 there is no guarantee that the correct record will be refreshed. The
2691 table's columns are refreshed to reflect the current data in the database.
2694 \membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
2696 \func{void}{SetColDefs}{\param{int }{index}, \param{const char *}{fieldName}, \param{int }{dataType}, \param{void *}{pData}, \param{int }{cType}, \param{int }{size}, \param{bool }{keyField = FALSE}, \param{bool }{upd = TRUE}, \param{bool }{insAllow = TRUE}, \param{bool }{derivedCol = FALSE}}
2698 \func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{ULONG }{numCols}}
2700 \wxheading{Parameters}
2702 \docparam{index}{Column number (0 to n-1, where n is the number of columns
2703 specified as being defined for this wxDbTable instance when the
2704 wxDbTable constructor was called.}
2705 \docparam{fieldName}{Column name from the associated data table.}
2706 \docparam{dataType}{Logical data type. Valid logical types include:}
2709 DB_DATA_TYPE_VARCHAR : strings
2710 DB_DATA_TYPE_INTEGER : non-floating point numbers
2711 DB_DATA_TYPE_FLOAT : floating point numbers
2712 DB_DATA_TYPE_DATE : dates
2715 \docparam{pData}{Pointer to the data object that will hold the column's
2716 value when a row of data is returned from the datasource.}
2717 \docparam{cType}{SQL C Type. This defines the data type that the SQL
2718 representation of the data is converted to to be stored in {\it pData}.
2719 Other valid types are available also, but these are the most common ones:}
2722 SQL_C_CHAR // strings
2732 SQL_C_BOOLEAN // defined in db.h
2733 SQL_C_ENUM // defined in db.h
2736 \docparam{size}{Maximum size in bytes of the {\it pData} object.}
2737 \docparam{keyField}{{\it OPTIONAL}. Indicates if this column is part of the
2738 primary index. Default is FALSE.}
2739 \docparam{upd}{{\it OPTIONAL}. Are updates allowed on this column?
2741 \docparam{insAllow}{{\it OPTIONAL}. Inserts allowed on this column?
2743 \docparam{derivedCol}{{\it OPTIONAL}. Is this a derived column (non base
2744 table column for query only)? Default is FALSE.}
2746 \docparam{colInfs}{Pointer to an array of wxDbColInf instances which contains
2747 all the information necessary to create {\it numCols} column definitions.}
2748 \docparam{numCols}{Number of elements of wxDbColInf type that are pointed
2749 to by {\it colInfs}, which are to have column definitions created from them.}
2753 If {\it pData} is to hold a string of characters, be sure to include enough
2754 space for the NULL terminator in pData and in the byte count of {\it size}.
2756 Both forms of this function provide a shortcut for defining the columns in
2757 your wxDbTable object. Use this function in any derived wxDbTable
2758 constructor when describing the column/columns in the wxDbTable object.
2760 The second form of this function is primarily used when the
2761 \helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
2762 datasource for the column definitions, so that the column definitions are
2763 already stored in wxDbColInf form. One example use of using
2764 \helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
2765 a data table existed in one datasource, and the table's column definitions
2766 were to be copied over to another datasource or table.
2771 // Long way not using this function
2772 strcpy(colDefs[0].ColName, "PART_NO");
2773 colDefs[0].DbDataType = DB_DATA_TYPE_VARCHAR;
2774 colDefs[0].PtrDataObj = PartNumber;
2775 colDefs[0].SqlCtype = SQL_C_CHAR;
2776 colDefs[0].SzDataObj = PART_NUMBER_LEN;
2777 colDefs[0].KeyField = TRUE;
2778 colDefs[0].Updateable = FALSE;
2779 colDefs[0].InsertAllowed= TRUE;
2780 colDefs[0].DerivedCol = FALSE;
2782 // Shortcut using this function
2783 SetColDefs(0, "PART_NUMBER", DB_DATA_TYPE_VARCHAR, PartNumber,
2784 SQL_C_CHAR, PART_NUMBER_LEN, TRUE, FALSE,TRUE,FALSE);
2788 \membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
2790 \func{bool}{Open}{\param{HSTMT *}{hstmtActivate = (void **) wxDB_DEFAULT_CURSOR
}}
2792 \wxheading{Parameters
}
2794 \docparam{hstmtActivate
}{{\it OPTIONAL
}. Pointer to the cursor that is to
2795 become the current cursor. Passing no cursor handle will reset the cursor
2796 back to the wxDbTable's default (original) cursor that was created when the
2797 wxDbTable instance was first created. Default is wxDB_DEFAULT_CURSOR.
}
2801 When swapping between cursors, the member variables of the wxDbTable object
2802 are automatically refreshed with the column values of the row that the
2803 current cursor is positioned at (if any). If the cursor is not positioned,
2804 then the data in member variables is undefined.
2806 The only way to return back to the cursor that was in use before this
2807 function was called is to programmatically determine the current cursor
2808 BEFORE calling this function using
\helpref{wxDbTable::GetCursor
}{wxdbtablegetcursor
}
2809 and saving a pointer to that cursor.
2811 \wxheading{See also
}
2813 \helpref{wxDbTable::GetNewCursor
}{wxdbtablegetnewcursor
},
\helpref{wxDbTable::GetCursor
}{wxdbtablegetcursor
},
2814 \helpref{wxDbTable::SetCursor
}{wxdbtablesetcursor
}
2817 \membersection{wxDbTable::SetFromClause
}\label{wxdbtablesetfromclause
}
2819 \func{void
}{SetFromClause
}{\param{const wxString &
}{From
}}
2821 Accessor function for setting the private class member wxDbTable::from
2822 that indicates what other tables should be outer joined with the wxDbTable's
2823 base table for access to the columns in those other tables.
2825 Synonym to this function is one form of
\helpref{wxDbTable::From
}{wxdbtablefrom
}
2827 \wxheading{Parameters
}
2829 \docparam{From
}{A comma separated list of table names that are to be outer
2830 joined with the base table's columns so that the joined table's columns
2831 may be returned in the result set or used as a portion of a comparison with
2832 the base table's columns. NOTE that the base tables name must NOT be included
2833 in the FROM clause, as it is automatically included by the wxDbTable class
2834 in constructing query statements.
}
2838 Used by the
\helpref{wxDbTable::Query
}{wxdbtablequery
} and
2839 \helpref{wxDbTable::Count
}{wxdbtablecount
} member functions to allow outer
2840 joining of records from multiple tables.
2842 Do
{\bf not
} include the keyword "FROM" when setting the FROM clause.
2844 If using the FROM clause when performing a query, be certain to include in
2845 the corresponding WHERE clause a comparison of a column from either the base
2846 table or one of the other joined tables to each other joined table to ensure
2847 the datasource knows on which column values the tables should be joined on.
2853 // Base table is the "LOCATION" table, and it is being
2854 // outer joined to the "PART" table via the the field "PART_NUMBER"
2855 // that can be related between the two tables.
2856 location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
2857 location->SetFromClause("PART");
2861 \wxheading{See also
}
2863 \helpref{wxDbTable::From
}{wxdbtablefrom
},
2864 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2867 \membersection{wxDbTable::SetNull
}\label{wxdbtablesetnull
}
2869 \func{bool
}{SetNull
}{\param{int
}{colNo
}}
2871 \func{bool
}{SetNull
}{\param{const char *
}{colName
}}
2873 Both forms of this function allow a member variable representing a column
2874 in the table associated with this wxDbTable object to be set to NULL.
2876 The first form allows the column to be set by the index into the column
2877 definitions used to create the wxDbTable instance, while the second allows
2878 the actual column name to be specified.
2880 \wxheading{Parameters
}
2882 \docparam{colNo
}{Index into the column definitions used when first defining
2883 this wxDbTable object.
}
2884 \docparam{colName
}{Actual data table column name that is to be set to NULL.
}
2888 No database updates are done by this function. It only operates on the
2889 member variables in memory. Use and insert or update function to store this
2893 \membersection{wxDbTable::SetOrderByClause
}\label{wxdbtablesetorderbyclause
}
2895 \func{void
}{SetOrderByClause
}{\param{const wxString &
}{OrderBy
}}
2897 Accessor function for setting the private class member wxDbTable::orderBy
2898 which determines sequence/ordering of the rows returned in the result set
2901 Synonym to this function is one form of
\helpref{wxDbTable::OrderBy
}{wxdbtableorderby
}
2903 \wxheading{Parameters
}
2905 \docparam{OrderBy
}{A comma separated list of column names that indicate the
2906 alphabetized sorting sequence that the result set is to be returned in. If
2907 a FROM clause has also been specified, each column name specified in the
2908 ORDER BY clause should be prefaced with the table name to which the column
2909 belongs using DOT notation (TABLE.COLUMN).
}
2913 Do
{\bf not
} include the keywords "ORDER BY" when setting the ORDER BY clause.
2919 parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
2923 location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
2927 \wxheading{See also
}
2929 \helpref{wxDbTable::OrderBy
}{wxdbtableorderby
},
2930 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}
2933 \membersection{wxDbTable::SetQueryTimeout
}\label{wxdbtablesetquerytimeout
}
2935 \func{bool
}{SetQueryTimeout
}{\param{UDWORD
}{nSeconds
}}
2937 Allows a time period to be set as the timeout period for queries.
2939 \wxheading{Parameters
}
2941 \docparam{nSeconds
}{The number of seconds to wait for the query to complete
2946 Neither Oracle or Access support this function as of yet. Other databases
2947 should be evaluated for support before depending on this function working
2951 \membersection{wxDbTable::SetWhereClause
}\label{wxdbtablesetwhereclause
}
2953 \func{void
}{SetWhereClause
}{\param{const wxString &
}{Where
}}
2955 Accessor function for setting the private class member wxDbTable::where
2956 that determines which rows are returned in the result set by the datasource.
2958 Synonym to this function is one form of
\helpref{wxDbTable::Where
}{wxdbtablewhere
}
2960 \wxheading{Parameters
}
2962 \docparam{Where
}{SQL "where" clause. This clause can contain any SQL language
2963 that is legal in standard where clauses. If a FROM clause has also been
2964 specified, each column name specified in the ORDER BY clause should be
2965 prefaced with the table name to which the column belongs using DOT notation
2970 Do
{\bf not
} include the keywords "WHERE" when setting the WHERE clause.
2976 // Simple where clause
2977 parts->SetWhereClause("PART_NUMBER = '
32'");
2979 // Any comparison operators
2980 parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER
%'");
2982 // Multiple comparisons, including a function call
2983 parts->Where("QTY >
0 AND
{fn UCASE(PART_DESCRIP)
} LIKE '
%DRILL%'");
2985 // Using parameters and multiple logical combinations
2986 parts->Where("((QTY >
10) OR (ON_ORDER >
0)) AND ON_HOLD =
0");
2988 // This query uses an outer join (requiring a FROM clause also)
2989 // that joins the PART and LOCATION table on he common field
2991 parts->Where("PART.ON_HOLD =
0 AND \
2992 PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
2993 LOCATION.PART_NUMBER >
0");
2997 \membersection{wxDbTable::Update
}\label{wxdbtableupdate
}
2999 \func{bool
}{Update
}{\void}
3001 \func{bool
}{Update
}{\param{const char *
}{pSqlStmt
}}
3003 This member function
3005 The first form of this function will update the row that the current cursor
3006 is currently positioned at with the values in the memory variables that
3007 are bound to the columns. The actual SQL statement to perform the update
3008 is automatically created by the ODBC class, and then executed.
3010 The second form of the function allows full access through SQL statements for
3011 updating records in the database. Write any valid SQL UPDATE statement and
3012 submit it to this function for execution. Sophisticated updates can be
3013 performed using the full power of the SQL dialect. The full SQL statement
3014 must have the exact syntax required by the driver/datasource for performing
3015 the update. This usually is in the form of:
3018 UPDATE tablename SET col1=X, col2=Y, ... where ...
3021 \wxheading{Parameters
}
3023 \docparam{pSqlStmt
}{Pointer to SQL UPDATE statement to be executed.
}
3027 Note that using this function when it is associated with the table that the
3028 wxDbTable instance is associated with does not prevent updating
3029 columns in any other table in the database for which the connected user
3030 has update privileges on. Constructing the appropriate full SQL statement,
3031 columns in other tables can also be updated as well.
3033 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
3034 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
3035 this function to commit or rollback the update.
3040 strcpy(sqlStmt, "update PART set QTY =
0 where PART_NUMBER = '
32'");
3044 \membersection{wxDbTable::UpdateWhere
}\label{wxdbtableupdatewhere
}
3046 \func{bool
}{UpdateWhere
}{\param{const char *
}{pWhereClause
}}
3048 Performs updates to the base table of the wxDbTable object, updating only the
3049 rows which match the criteria specified in the
{\it pWhereClause
}.
3051 All columns that are bound to member variables for this wxDbTable instance
3052 that were defined with the "updateable" parameter set to TRUE will be updated
3053 with the information currently held in the memory variable.
3055 \wxheading{Parameters
}
3057 \docparam{pWhereClause
}{Pointer to a valid SQL WHERE clause. Do not
3058 include the keyword 'WHERE'.
}
3062 Care should be used when updating columns that are part of indexes with
3063 this function so as not to violate an unique key constraints.
3065 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
3066 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
3067 this function to commit or rollback the update(s).
3070 \membersection{wxDbTable::operator $++$
}\label{wxdbtableplusplus
}
3072 \func{bool
}{operator $++$
}{\void}
3074 Synonym for
\helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}
3076 \wxheading{See also
}
3078 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}
3081 \membersection{wxDbTable::operator $--$
}\label{wxdbtableminusminus
}
3083 \func{bool
}{operator $--$
}{\void}
3085 Synonym for
\helpref{wxDbTable::GetPrev
}{wxdbtablegetprev
}
3087 \wxheading{See also
}
3089 \helpref{wxDbTable::GetPrev
}{wxdbtablegetprev
}
3092 \section{\class{wxDbTableInf
}}\label{wxdbtableinf
}
3094 Currently only used by wxDb::GetCatalog() internally and wxDbInf class,
3095 but may be used in future releases for user functions. Contains information
3096 describing the table (Name, type, etc). A pointer to a wxDbColInf array
3097 instance is included so a program can create a wxDbColInf array instance
3098 (using
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
}) to maintain all information about the columns
3099 of a table in one memory structure.