1 \section{\class{wxDb
}}\label{wxdb
}
3 A wxDb instance is a connection to an ODBC datasource 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 datasource, as well as allowing access to any tables/views defined in
7 the datasource to which the user has sufficient privileges.
9 See the
\helpref{database classes overview
}{odbcoverview
} for
10 an introduction to using the ODBC classes.
12 \wxheading{Include files
}
16 \wxheading{Helper classes and data structures
}
18 The following classes and structs are defined in db.cpp/.h for use with the wxDb class.
20 \begin{itemize
}\itemsep=
0pt
21 \item \helpref{wxDbColFor
}{wxdbcolfor
}
22 \item \helpref{wxDbColInf
}{wxdbcolinf
}
23 \item \helpref{wxDbTableInf
}{wxdbtableinf
}
24 \item \helpref{wxDbInf
}{wxdbinf
}
29 NOTE: In a future release, all ODBC class constants will be prefaced with 'wx'.
32 wxDB_PATH_MAX Maximum path length allowed to be passed to
33 the ODBC driver to indicate where the data
36 DB_MAX_COLUMN_NAME_LEN Maximum supported length for the name of a
39 DB_MAX_ERROR_HISTORY Maximum number of error messages retained in
40 the queue before being overwritten by new
43 DB_MAX_ERROR_MSG_LEN Maximum supported length of an error message
44 returned by the ODBC classes
46 DB_MAX_STATEMENT_LEN Maximum supported length for a complete SQL
47 statement to be passed to the ODBC driver
49 DB_MAX_TABLE_NAME_LEN Maximum supported length for the name of a
52 DB_MAX_WHERE_CLAUSE_LEN Maximum supported WHERE clause length that
53 can be passed to the ODBC driver
55 DB_TYPE_NAME_LEN Maximum length of the name of a column's
59 \subsection{Enumerated types
}\label{wxdbenumeratedtypes
}
61 \wxheading{Enumerated types
}
63 \docparam{enum
{\bf wxDbSqlLogState
}}{sqlLogOFF, sqlLogON
}
65 {\it enum
{\bf wxDBMS
}}
67 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.
69 \begin{itemize
}\itemsep=
0pt
75 \item MS SQL Server (v7 - minimal testing)
76 \item MS Access (
97,
2000,
2002, and
2003)
77 \item MySQL (
2.x and
3.5 - use the
2.5x drivers though)
78 \item Oracle (v7, v8, v8i)
81 \item Sybase (ASA and ASE)
86 See the remarks in
\helpref{wxDb::Dbms
}{wxdbdbms
} for exceptions/issues with each of these database engines.
88 \wxheading{Public member variables
}
90 \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.
}
92 \docparam{int
{\bf wxDb::DB
\_STATUS}}{The last ODBC error/status that occurred on this data connection. Possible codes are:
}
95 DB_ERR_GENERAL_WARNING // SqlState = '
01000'
96 DB_ERR_DISCONNECT_ERROR // SqlState = '
01002'
97 DB_ERR_DATA_TRUNCATED // SqlState = '
01004'
98 DB_ERR_PRIV_NOT_REVOKED // SqlState = '
01006'
99 DB_ERR_INVALID_CONN_STR_ATTR // SqlState = '
01S00'
100 DB_ERR_ERROR_IN_ROW // SqlState = '
01S01'
101 DB_ERR_OPTION_VALUE_CHANGED // SqlState = '
01S02'
102 DB_ERR_NO_ROWS_UPD_OR_DEL // SqlState = '
01S03'
103 DB_ERR_MULTI_ROWS_UPD_OR_DEL // SqlState = '
01S04'
104 DB_ERR_WRONG_NO_OF_PARAMS // SqlState = '
07001'
105 DB_ERR_DATA_TYPE_ATTR_VIOL // SqlState = '
07006'
106 DB_ERR_UNABLE_TO_CONNECT // SqlState = '
08001'
107 DB_ERR_CONNECTION_IN_USE // SqlState = '
08002'
108 DB_ERR_CONNECTION_NOT_OPEN // SqlState = '
08003'
109 DB_ERR_REJECTED_CONNECTION // SqlState = '
08004'
110 DB_ERR_CONN_FAIL_IN_TRANS // SqlState = '
08007'
111 DB_ERR_COMM_LINK_FAILURE // SqlState = '
08S01'
112 DB_ERR_INSERT_VALUE_LIST_MISMATCH // SqlState = '
21S01'
113 DB_ERR_DERIVED_TABLE_MISMATCH // SqlState = '
21S02'
114 DB_ERR_STRING_RIGHT_TRUNC // SqlState = '
22001'
115 DB_ERR_NUMERIC_VALUE_OUT_OF_RNG // SqlState = '
22003'
116 DB_ERR_ERROR_IN_ASSIGNMENT // SqlState = '
22005'
117 DB_ERR_DATETIME_FLD_OVERFLOW // SqlState = '
22008'
118 DB_ERR_DIVIDE_BY_ZERO // SqlState = '
22012'
119 DB_ERR_STR_DATA_LENGTH_MISMATCH // SqlState = '
22026'
120 DB_ERR_INTEGRITY_CONSTRAINT_VIOL // SqlState = '
23000'
121 DB_ERR_INVALID_CURSOR_STATE // SqlState = '
24000'
122 DB_ERR_INVALID_TRANS_STATE // SqlState = '
25000'
123 DB_ERR_INVALID_AUTH_SPEC // SqlState = '
28000'
124 DB_ERR_INVALID_CURSOR_NAME // SqlState = '
34000'
125 DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL // SqlState = '
37000'
126 DB_ERR_DUPLICATE_CURSOR_NAME // SqlState = '
3C000'
127 DB_ERR_SERIALIZATION_FAILURE // SqlState = '
40001'
128 DB_ERR_SYNTAX_ERROR_OR_ACCESS_VIOL2 // SqlState = '
42000'
129 DB_ERR_OPERATION_ABORTED // SqlState = '
70100'
130 DB_ERR_UNSUPPORTED_FUNCTION // SqlState = 'IM001'
131 DB_ERR_NO_DATA_SOURCE // SqlState = 'IM002'
132 DB_ERR_DRIVER_LOAD_ERROR // SqlState = 'IM003'
133 DB_ERR_SQLALLOCENV_FAILED // SqlState = 'IM004'
134 DB_ERR_SQLALLOCCONNECT_FAILED // SqlState = 'IM005'
135 DB_ERR_SQLSETCONNECTOPTION_FAILED // SqlState = 'IM006'
136 DB_ERR_NO_DATA_SOURCE_DLG_PROHIB // SqlState = 'IM007'
137 DB_ERR_DIALOG_FAILED // SqlState = 'IM008'
138 DB_ERR_UNABLE_TO_LOAD_TRANSLATION_DLL // SqlState = 'IM009'
139 DB_ERR_DATA_SOURCE_NAME_TOO_LONG // SqlState = 'IM010'
140 DB_ERR_DRIVER_NAME_TOO_LONG // SqlState = 'IM011'
141 DB_ERR_DRIVER_KEYWORD_SYNTAX_ERROR // SqlState = 'IM012'
142 DB_ERR_TRACE_FILE_ERROR // SqlState = 'IM013'
143 DB_ERR_TABLE_OR_VIEW_ALREADY_EXISTS // SqlState = 'S0001'
144 DB_ERR_TABLE_NOT_FOUND // SqlState = 'S0002'
145 DB_ERR_INDEX_ALREADY_EXISTS // SqlState = 'S0011'
146 DB_ERR_INDEX_NOT_FOUND // SqlState = 'S0012'
147 DB_ERR_COLUMN_ALREADY_EXISTS // SqlState = 'S0021'
148 DB_ERR_COLUMN_NOT_FOUND // SqlState = 'S0022'
149 DB_ERR_NO_DEFAULT_FOR_COLUMN // SqlState = 'S0023'
150 DB_ERR_GENERAL_ERROR // SqlState = 'S1000'
151 DB_ERR_MEMORY_ALLOCATION_FAILURE // SqlState = 'S1001'
152 DB_ERR_INVALID_COLUMN_NUMBER // SqlState = 'S1002'
153 DB_ERR_PROGRAM_TYPE_OUT_OF_RANGE // SqlState = 'S1003'
154 DB_ERR_SQL_DATA_TYPE_OUT_OF_RANGE // SqlState = 'S1004'
155 DB_ERR_OPERATION_CANCELLED // SqlState = 'S1008'
156 DB_ERR_INVALID_ARGUMENT_VALUE // SqlState = 'S1009'
157 DB_ERR_FUNCTION_SEQUENCE_ERROR // SqlState = 'S1010'
158 DB_ERR_OPERATION_INVALID_AT_THIS_TIME // SqlState = 'S1011'
159 DB_ERR_INVALID_TRANS_OPERATION_CODE // SqlState = 'S1012'
160 DB_ERR_NO_CURSOR_NAME_AVAIL // SqlState = 'S1015'
161 DB_ERR_INVALID_STR_OR_BUF_LEN // SqlState = 'S1090'
162 DB_ERR_DESCRIPTOR_TYPE_OUT_OF_RANGE // SqlState = 'S1091'
163 DB_ERR_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1092'
164 DB_ERR_INVALID_PARAM_NO // SqlState = 'S1093'
165 DB_ERR_INVALID_SCALE_VALUE // SqlState = 'S1094'
166 DB_ERR_FUNCTION_TYPE_OUT_OF_RANGE // SqlState = 'S1095'
167 DB_ERR_INF_TYPE_OUT_OF_RANGE // SqlState = 'S1096'
168 DB_ERR_COLUMN_TYPE_OUT_OF_RANGE // SqlState = 'S1097'
169 DB_ERR_SCOPE_TYPE_OUT_OF_RANGE // SqlState = 'S1098'
170 DB_ERR_NULLABLE_TYPE_OUT_OF_RANGE // SqlState = 'S1099'
171 DB_ERR_UNIQUENESS_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1100'
172 DB_ERR_ACCURACY_OPTION_TYPE_OUT_OF_RANGE // SqlState = 'S1101'
173 DB_ERR_DIRECTION_OPTION_OUT_OF_RANGE // SqlState = 'S1103'
174 DB_ERR_INVALID_PRECISION_VALUE // SqlState = 'S1104'
175 DB_ERR_INVALID_PARAM_TYPE // SqlState = 'S1105'
176 DB_ERR_FETCH_TYPE_OUT_OF_RANGE // SqlState = 'S1106'
177 DB_ERR_ROW_VALUE_OUT_OF_RANGE // SqlState = 'S1107'
178 DB_ERR_CONCURRENCY_OPTION_OUT_OF_RANGE // SqlState = 'S1108'
179 DB_ERR_INVALID_CURSOR_POSITION // SqlState = 'S1109'
180 DB_ERR_INVALID_DRIVER_COMPLETION // SqlState = 'S1110'
181 DB_ERR_INVALID_BOOKMARK_VALUE // SqlState = 'S1111'
182 DB_ERR_DRIVER_NOT_CAPABLE // SqlState = 'S1C00'
183 DB_ERR_TIMEOUT_EXPIRED // SqlState = 'S1T00'
186 \docparam{struct
{\bf wxDb::dbInf
}}{This structure is internal to the
187 wxDb class and contains details of the ODBC datasource that the current
188 instance of the wxDb is connected to in its members. When the datasource
189 is opened, all of the information contained in the dbInf structure is
190 queried from the datasource. This information is used almost exclusively
191 within the ODBC class library. Where there may be a need for particular
192 portions of this information outside of the class library, member
194 \helpref{wxDbTable::IsCursorClosedOnCommit
}{wxdbtableiscursorclosedoncommit
})
195 have been added for ease of use.
}
198 wxChar dbmsName
[40] - Name of the dbms product
199 wxChar dbmsVer
[64] - Version # of the dbms product
200 wxChar driverName
[40] - Driver name
201 wxChar odbcVer
[60] - ODBC version of the driver
202 wxChar drvMgrOdbcVer
[60] - ODBC version of the driver manager
203 wxChar driverVer
[60] - Driver version
204 wxChar serverName
[80] - Server Name, typically a connect string
205 wxChar databaseName
[128] - Database filename
206 wxChar outerJoins
[2] - Does datasource support outer joins
207 wxChar procedureSupport
[2] - Does datasource support stored
209 UWORD maxConnections - Maximum # of connections datasource
211 UWORD maxStmts - Maximum # of HSTMTs per HDBC
212 UWORD apiConfLvl - ODBC API conformance level
213 UWORD cliConfLvl - Is datasource SAG compliant
214 UWORD sqlConfLvl - SQL conformance level
215 UWORD cursorCommitBehavior - How cursors are affected on db commit
216 UWORD cursorRollbackBehavior - How cursors are affected on db
218 UWORD supportNotNullClause - Does datasource support NOT NULL
220 wxChar supportIEF
[2] - Integrity Enhancement Facility (Ref.
222 UDWORD txnIsolation - Transaction isolation level supported by
224 UDWORD txnIsolationOptions - Transaction isolation level options
226 UDWORD fetchDirections - Fetch directions supported
227 UDWORD lockTypes - Lock types supported in SQLSetPos
228 UDWORD posOperations - Position operations supported in
230 UDWORD posStmts - Position statements supported
231 UDWORD scrollConcurrency - Scrollable cursor concurrency options
233 UDWORD scrollOptions - Scrollable cursor options supported
234 UDWORD staticSensitivity - Can additions/deletions/updates be
236 UWORD txnCapable - Indicates if datasource supports
238 UDWORD loginTimeout - Number seconds to wait for a login
242 \docparam{wxChar
{\bf wxDb::errorList
}[DB
\_MAX\_ERROR\_HISTORY][DB
\_MAX\_ERROR\_MSG\_LEN]}{The last n ODBC errors that have occurred on this database connection.
}
244 \docparam{wxChar
{\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.
}
246 \docparam{SDWORD
{\bf wxDb::nativeError
}}{Set by wxDb::DispAllErrors,
247 wxDb::GetNextError, and wxDb::DispNextError. It contains the
248 datasource-specific error code returned by the datasource to the ODBC driver.
249 Used for reporting ODBC errors.
}
251 \docparam{wxChar
{\bf wxDb::sqlState
}[20]}{Set by wxDb::TranslateSqlState().
252 Indicates the error state after a failed ODBC operation. Used for reporting
257 Default cursor scrolling is defined by wxODBC
\_FWD\_ONLY\_CURSORS in setup.h
258 when the wxWidgets library is built. This behavior can be overridden when
259 an instance of a wxDb is created (see
\helpref{wxDb constructor
}{wxdbctor
}).
260 Default setting of this value true, as not all databases/drivers support
261 both types of cursors.
265 \helpref{wxDbColFor
}{wxdbcolfor
},
\helpref{wxDbColInf
}{wxdbcolinf
},
266 \helpref{wxDbTable
}{wxdbtable
},
\helpref{wxDbTableInf
}{wxdbtableinf
},
267 \helpref{wxDbInf
}{wxdbinf
}
269 \subsection{Associated non-class functions
}\label{wxdbfunctions
}
271 The following functions are used in conjunction with the wxDb class.
273 \func{void
}{wxDbCloseConnections
}{\void}
277 Closes all cached connections that have been made through use of the
278 \helpref{wxDbGetConnection
}{wxdbfunctions
} function.
280 NOTE: These connections are closed regardless of whether they are in use
281 or not. This function should only be called after the program has
282 finished using the connections and all wxDbTable instances that use any of
283 the connections have been closed.
285 This function performs a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
286 on the connection before closing it to commit any changes that are still
287 pending, as well as to avoid any function sequence errors upon closing
291 \func{int
}{wxDbConnectionsInUse
}{\void}
295 Returns a count of how many database connections are currently free ( not
296 being used) that have been cached through use of the
\helpref{wxDbGetConnection
}{wxdbfunctions
}
300 \func{bool
}{wxDbFreeConnection
}{\param{wxDb *
}{pDb
}}
304 Searches the list of cached database connections connection for one matching
305 the passed in wxDb instance. If found, that cached connection is freed.
307 Freeing a connection means that it is marked as available (free) in the
308 cache of connections, so that a call to
\helpref{wxDbGetConnection
}{wxdbfunctions
}
309 is able to return a pointer to the wxDb instance for use. Freeing a
310 connection does NOT close the connection, it only makes the connection
314 \func{wxDb *
}{wxDbGetConnection
}{\param{wxDbConnectInf *
}{pDbConfig
},
315 \param{bool
}{FwdOnlyCursors=(bool)wxODBC
\_FWD\_ONLY\_CURSORS}}
319 This function is used to request a "new" wxDb instance for use by the program.
320 The wxDb instance returned is also opened (see
\helpref{wxDb::Open
}{wxdbopen
}).
322 This function (along with wxDbFreeConnection() and wxDbCloseConnection())
323 maintain a cache of wxDb instances for user/re-use by a program. When a
324 program needs a wxDb instance, it may call this function to obtain a wxDb
325 instance. If there is a wxDb instance in the cache that is currently unused
326 that matches the connection requirements specified in
{\it'pDbConfig'
} then
327 that cached connection is marked as no longer being free, and a pointer to
328 the wxDb instance is returned.
330 If there are no connections available in the cache that meet the requirements
331 given in
{\it'pDbConfig'
}, then a new wxDb instance is created to connect
332 to the datasource specified in
{\it'pDbConfig'
} using the userID and password
333 given in
{\it'pDbConfig'
}.
335 NOTE: The caching routine also uses the
\helpref{wxDb::Open
}{wxdbopen
}
336 connection datatype copying code. If the call to wxDbGetConnection()
337 requests a connection to a datasource, and there is not one available in the
338 cache, a new connection is created. But when the connection is opened,
339 instead of polling the datasource over again for its datatypes, if a
340 connection to the same datasource (using the same userID/password) has already
341 been done previously, the new connection skips querying the datasource for
342 its datatypes, and uses the same datatypes determined previously by the
343 other connection(s) for that same datasource. This cuts down greatly on
344 network traffic, database load, and connection creation time.
346 When the program is done using a connection created through a call to
347 wxDbGetConnection(), the program should call wxDbFreeConnection() to release
348 the wxDb instance back to the cache. DO NOT DELETE THE wxDb INSTANCE!
349 Deleting the wxDb instance returned can cause a crash/memory corruption
350 later in the program when the cache is cleaned up.
352 When exiting the program, call wxDbCloseConnections() to close all the
353 cached connections created by calls to wxDbGetConnection().
356 \func{const wxChar *
}{wxDbLogExtendedErrorMsg
}{\param{const wxChar *
}{userText
},
\param{wxDb *
}{pDb
},
\param{wxChar *
}{ErrFile
},
\param{int
}{ErrLine
}}
358 Writes a message to the wxLog window (stdout usually) when an internal
359 error situation occurs.
361 \func{bool
}{wxDbSqlLog
}{\param{wxDbSqlLogState
}{state
},
\param{const wxString \&
}{filename = SQL
\_LOG\_FILENAME}}
365 This function sets the sql log state for all open wxDb objects
367 \func{bool
}{wxDbGetDataSource
}{\param{HENV
}{henv
},
\param{wxChar *
}{Dsn
},
\param{SWORD
}{DsnMax
},
\param{wxChar *
}{DsDesc
},
\param{SWORD
}{DsDescMax
},
\param{UWORD
}{direction = SQL
\_FETCH\_NEXT}}
371 This routine queries the ODBC driver manager for a list of available
372 datasources. Repeatedly call this function to obtain all the datasources
373 available through the ODBC driver manager on the current workstation.
376 wxArrayString strArray;
378 while (wxDbGetDataSource(DbConnectInf.GetHenv(), Dsn, SQL_MAX_DSN_LENGTH+
1, DsDesc,
255))
382 \latexignore{\rtfignore{\wxheading{Members
}}}
384 \membersection{wxDb::wxDb
}\label{wxdbctor
}
390 \func{}{wxDb
}{\param{const HENV \&
}{aHenv
},
\param{bool
}{FwdOnlyCursors=(bool)wxODBC
\_FWD\_ONLY\_CURSORS}}
392 Constructor, used to create an ODBC connection to a datasource.
394 \wxheading{Parameters
}
396 \docparam{aHenv
}{Environment handle used for this connection. See
397 \helpref{wxDConnectInf::AllocHenv
}{wxdbconnectinfallochenv
}}
399 \docparam{FwdOnlyCursors
}{Will cursors created for use with this datasource
400 connection only allow forward scrolling cursors.
}
404 This is the constructor for the wxDb class. The wxDb object must
405 be created and opened before any database activity can occur.
410 wxDbConnectInf ConnectInf;
411 ....Set values for member variables of ConnectInf here
413 wxDb sampleDB(ConnectInf.GetHenv());
414 if (!sampleDB.Open(ConnectInf.GetDsn(), ConnectInf.GetUserID(),
415 ConnectInf.GetPassword()))
417 // Error opening datasource
423 \helpref{wxDbGetConnection
}{wxdbfunctions
}
425 \membersection{wxDb::Catalog
}\label{wxdbcatalog
}
427 \func{bool
}{Catalog
}{\param{wxChar *
}{ userID
},
\param{const wxString \&
}{fileName =
428 SQL
\_CATALOG\_FILENAME}}
430 Allows a data "dictionary" of the datasource to be created, dumping pertinent
431 information about all data tables to which the user specified in userID has
434 \wxheading{Parameters
}
436 \docparam{userID
}{Database user name to use in accessing the database. All
437 tables to which this user has rights will be evaluated in the catalog.
}
439 \docparam{fileName
}{{\it OPTIONAL
}. Name of the text file to create and write
440 the DB catalog to. Default is SQL
\_CATALOG\_FILENAME.
}
442 \wxheading{Return value
}
444 Returns true if the catalog request was successful, or false if there was some
445 reason that the catalog could not be generated.
450 ============== ============== ================ ========= =======
451 TABLE NAME COLUMN NAME DATA TYPE PRECISION LENGTH
452 ============== ============== ================ ========= =======
453 EMPLOYEE RECID (
0008)NUMBER
15 8
454 EMPLOYEE USER_ID (
0012)VARCHAR2
13 13
455 EMPLOYEE FULL_NAME (
0012)VARCHAR2
26 26
456 EMPLOYEE PASSWORD (
0012)VARCHAR2
26 26
457 EMPLOYEE START_DATE (
0011)DATE
19 16
461 \membersection{wxDb::Close
}\label{wxdbclose
}
463 \func{void
}{Close
}{\void}
465 Closes the database connection.
469 At the end of your program, when you have finished all of your database work,
470 you must close the ODBC connection to the datasource. There are actually
471 four steps involved in doing this as illustrated in the example.
473 Any wxDbTable instances which use this connection must be deleted before
474 closing the database connection.
479 // Commit any open transactions on the datasource
480 sampleDB.CommitTrans();
482 // Delete any remaining wxDbTable objects allocated with new
485 // Close the wxDb connection when finished with it
490 \membersection{wxDb::CommitTrans
}\label{wxdbcommittrans
}
492 \func{bool
}{CommitTrans
}{\void}
494 Permanently "commits" changes (insertions/deletions/updates) to the database.
496 \wxheading{Return value
}
498 Returns true if the commit was successful, or false if the commit failed.
502 Transactions begin implicitly as soon as you make a change to the database
503 with an insert/update/delete, or any other direct SQL command that performs
504 one of these operations against the datasource.
505 At any time thereafter, to save the changes to disk permanently, "commit"
506 them by calling this function.
508 Calling this member function commits ALL open transactions on this ODBC
509 connection. For example, if three different wxDbTable instances used the
510 same connection to the datasource, committing changes made on one of those
511 wxDbTable instances commits any pending transactions on all three wxDbTable
514 Until a call to wxDb::CommitTrans() is made, no other user or cursor is able
515 to see any changes made to the row(s) that have been inserted/modified/deleted.
518 \wxheading{Special Note :
{\it Cursors
} }
520 \normalbox{It is important to understand that different database/ODBC driver
521 combinations handle transactions differently. One thing in particular that
522 you must pay attention to is cursors, in regard to transactions. Cursors are
523 what allow you to scroll through records forward and backward and to
524 manipulate records as you scroll through them. When you issue a query, a
525 cursor is created behind the scenes. The cursor keeps track of the query and
526 keeps track of the current record pointer. After you commit or rollback a
527 transaction, the cursor may be closed automatically. This is database
528 dependent, and with some databases this behavior can be controlled through
529 management functions. This means you would need to requery the datasource
530 before you can perform any additional work using this cursor. This is only
531 necessary however if the datasource closes the cursor after a commit or
533 \helpref{wxDbTable::IsCursorClosedOnCommit
}{wxdbtableiscursorclosedoncommit
}
534 member function to determine the datasource's transaction behavior. Note, in
535 many situations it is very inefficient to assume the cursor is closed and
536 always requery. This could put a significant, unnecessary load on datasources
537 that leave the cursors open after a transaction.
}
540 \membersection{wxDb::CreateView
}\label{wxdbcreateviews
}
542 \func{bool
}{CreateView
}{\param{const wxString \&
}{ viewName
},
543 \param{const wxString \&
}{ colList
},
\param{const wxString \&
}{pSqlStmt
}}
545 Creates a SQL VIEW of one or more tables in a single datasource. Note that
546 this function will only work against databases which support views (currently
547 only Oracle as of November
21 2000).
549 \wxheading{Parameters
}
551 \docparam{viewName
}{The name of the view. e.g. PARTS
\_V}
553 \docparam{colList
}{{\it OPTIONAL
} Pass in a comma delimited list of column
554 names if you wish to explicitly name each column in the result set. If not
555 desired, pass in an empty string and the column names from the associated
556 table(s) will be used.
}
558 \docparam{pSqlStmt
}{Pointer to the select statement portion of the CREATE
559 VIEW statement. Must be a complete, valid SQL SELECT statement.
}
563 A 'view' is a logical table that derives columns from one or more other
564 tables or views. Once the view is created, it can be queried exactly like
565 any other table in the database.
567 NOTE: Views are not available with all datasources. Oracle is one example
568 of a datasource which does support views.
573 // Incomplete code sample
574 db.CreateView("PARTS_SD1", "PN, PD, QTY",
575 "SELECT PART_NUM, PART_DESC, QTY_ON_HAND *
1.1 FROM PARTS \
576 WHERE STORAGE_DEVICE =
1");
578 // PARTS_SD1 can now be queried just as if it were a data table.
579 // e.g. SELECT PN, PD, QTY FROM PARTS_SD1
583 \membersection{wxDb::Dbms
}\label{wxdbdbms
}
585 \func{wxDBMS
}{Dbms
}{\void}
589 The return value will be of the enumerated type wxDBMS. This enumerated
590 type contains a list of all the currently tested and supported databases.
592 Additional databases may work with these classes, but the databases
593 returned by this function have been tested and confirmed to work with
596 Possible values returned by this function can be viewed in the
597 \helpref{Enumerated types
}{wxdbenumeratedtypes
} section of wxDb.
599 There are known issues with conformance to the ODBC standards with several
600 datasources supported by the wxWidgets ODBC classes. Please see the overview
601 for specific details on which datasource have which issues.
603 \wxheading{Return value
}
605 The return value will indicate which of the supported datasources is
606 currently connected to by this connection. In the event that the
607 datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.
610 \membersection{wxDb::DispAllErrors
}\label{wxdbdispallerrors
}
612 \func{bool
}{DispAllErrors
}{\param{HENV
}{ aHenv
},
\param{HDBC
}{ aHdbc = SQL
\_NULL\_HDBC},
\param{HSTMT
}{ aHstmt = SQL
\_NULL\_HSTMT}}
614 Used to log all database errors that occurred as a result of an executed
615 database command. This logging is automatic and also includes debug logging
616 when compiled in debug mode via
\helpref{wxLogDebug
}{wxlogdebug
}. If logging
617 is turned on via
\helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
}, then an
618 entry is also logged to the defined log file.
620 \wxheading{Parameters
}
622 \docparam{aHenv
}{Handle to the ODBC environment.
}
624 \docparam{aHdbc
}{Handle to the ODBC connection. Pass this in if the ODBC
625 function call that erred required a hdbc or hstmt argument.
}
627 \docparam{aHstmt
}{Handle to the ODBC statement being executed against. Pass
628 this in if the ODBC function call that failed required a hstmt argument.
}
632 This member function will log all of the ODBC error messages for the last
633 ODBC function call that was made. This function is normally used internally
634 within the ODBC class library, but can be used programmatically after calling
635 ODBC functions directly (i.e. SQLFreeEnv()).
637 \wxheading{Return value
}
639 The function always returns false, so a call to this function can be made
640 in the return statement of a code block in the event of a failure to
641 perform an action (see the example below).
645 \helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
}, wxDbSqlLog
650 if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
651 // Display all ODBC errors for this stmt
652 return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
655 \membersection{wxDb::DispNextError
}\label{wxdbdispnexterror
}
657 \func{void
}{DispNextError
}{\void}
661 This function is normally used internally within the ODBC class library.
662 It could be used programmatically after calling ODBC functions directly. This
663 function works in conjunction with
\helpref{wxDb::GetNextError
}{wxdbgetnexterror
} when errors (or
664 sometimes informational messages) returned from ODBC need to be analyzed
665 rather than simply displaying them as an error. GetNextError() retrieves
666 the next ODBC error from the ODBC error queue. The wxDb member variables
667 "sqlState", "nativeError" and "errorMsg" could then be evaluated. To
668 display the error retrieved, DispNextError() could then be called.
669 The combination of GetNextError() and DispNextError() can be used to
670 iteratively step through the errors returned from ODBC evaluating each
671 one in context and displaying the ones you choose.
676 // Drop the table before attempting to create it
677 sprintf(sqlStmt, "DROP TABLE
%s", tableName);
678 // Execute the drop table statement
679 if (SQLExecDirect(hstmt,(UCHAR FAR *)sqlStmt,SQL_NTS) != SQL_SUCCESS)
681 // Check for sqlState = S0002, "Table or view not found".
682 // Ignore this error, bomb out on any other error.
683 pDb->GetNextError(henv, hdbc, hstmt);
684 if (wxStrcmp(pDb->sqlState, "S0002"))
686 pDb->DispNextError(); // Displayed error retrieved
687 pDb->DispAllErrors(henv, hdbc, hstmt); // Display all other errors, if any
688 pDb->RollbackTrans(); // Rollback the transaction
689 CloseCursor(); // Close the cursor
690 return(false); // Return Failure
696 \membersection{wxDb::DropView
}\label{wxdbdropview
}
698 \func{bool
}{DropView
}{\param{const wxString \&
}{viewName
}}
700 Drops the data table view named in 'viewName'.
702 \wxheading{Parameters
}
704 \docparam{viewName
}{Name of the view to be dropped.
}
708 If the view does not exist, this function will return true. Note that views are not supported with all datasources.
710 \membersection{wxDb::ExecSql
}\label{wxdbexecsql
}
712 \func{bool
}{ExecSql
}{\param{const wxString \&
}{pSqlStmt
}}
714 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.
716 \wxheading{Parameters
}
718 \docparam{pSqlStmt
}{Pointer to the SQL statement to be executed.
}
722 This member extends the wxDb class and allows you to build and execute ANY VALID
723 SQL statement against the datasource. This allows you to extend the class
724 library by being able to issue any SQL statement that the datasource is capable
729 \helpref{wxDb::GetData
}{wxdbgetdata
},
\helpref{wxDb::GetNext
}{wxdbgetnext
}
731 \membersection{wxDb::FwdOnlyCursors
}\label{wxdbfwdonlycursors
}
733 \func{bool
}{IsFwdOnlyCursors
}{\void}
735 Older form (pre-
2.3/
2.4 of wxWidgets) of the
736 \helpref{wxDb::IsFwdOnlyCursors
}{wxdbisfwdonlycursors
}. This method is
737 provided for backward compatibility only. The method
738 \helpref{wxDb::IsFwdOnlyCursors
}{wxdbisfwdonlycursors
} should be
739 used in place of this method.
742 \func{wxDbInf *
}{GetCatalog
}{\param{const wxChar *
}{userID
}}
744 \membersection{wxDb::GetCatalog
}\label{wxdbgetcatalog
}
746 \func{wxDbInf *
}{GetCatalog
}{\param{const wxChar *
}{userID
}}
748 Returns a
\helpref{wxDbInf
}{wxdbinf
} pointer that points to the catalog
749 (datasource) name, schema, number of tables accessible to the current user,
750 and a wxDbTableInf pointer to all data pertaining to all tables in the users
753 \wxheading{Parameters
}
755 \docparam{userID
}{Owner/Schema of the table. Specify a userID when the datasource you are connected to allows multiple unique tables with the same name to be owned by different users.
{\it userID
} is evaluated as follows:
}
758 userID == NULL ... UserID is ignored (DEFAULT)
759 userID == "" ... UserID set equal to 'this->uid'
760 userID != "" ... UserID set equal to 'userID'
765 The returned catalog will only contain catalog entries for tables to which the user specified in 'userID' has sufficient privileges. If no user is specified (NULL passed in), a catalog pertaining to all tables in the datasource accessible to the connected user (permissions apply) via this connection will be returned.
767 \membersection{wxDb::GetColumnCount
}\label{wxdbgetcolumncount
}
769 \func{int
}{GetColumnCount
}{\param{const wxString \&
}{tableName
},
\param{const wxChar *
}{userID
}}
771 \wxheading{Parameters
}
773 \docparam{tableName
}{The table name you wish to obtain column information about.
}
775 \docparam{userID
}{Name of the user that owns the table(s) (also referred to as schema).
776 Required for some datasources for situations where there may be multiple tables with the
777 same name in the datasource, but owned by different users.
{\it userID
} is
778 evaluated in the following manner:
}
781 userID == NULL ... UserID is ignored (DEFAULT)
782 userID == "" ... UserID set equal to 'this->uid'
783 userID != "" ... UserID set equal to 'userID'
786 \wxheading{Return value
}
788 Returns a count of how many columns are in the specified table. If an error
789 occurs retrieving the number of columns, this function will return a -
1.
791 \membersection{wxDb::GetColumns
}\label{wxdbgetcolumns
}
793 \func{wxDbColInf *
}{GetColumns
}{\param{const wxString \&
}{tableName
},
\param{UWORD *
}{numCols
},
\param{const wxChar *
}{userID=NULL
}}
795 \func{wxDbColInf *
}{GetColumns
}{\param{wxChar *
}{tableName
[]},
\param{const wxChar *
}{userID
}}
797 \wxheading{Parameters
}
799 \docparam{tableName
}{The table name you wish to obtain column information about.
}
800 \docparam{numCols
}{Pointer to a UWORD which will hold a count of the number of columns returned by this function
}
801 \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.
}
802 \docparam{userID
}{Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users.
{\it userID
} is evaluated in the following manner:
}
805 userID == NULL ... UserID is ignored (DEFAULT)
806 userID == "" ... UserID set equal to 'this->uid'
807 userID != "" ... UserID set equal to 'userID'
810 \wxheading{Return value
}
812 This function returns a pointer to an array of
\helpref{wxDbColInf
}{wxdbcolinf
}
813 structures, allowing you to obtain information regarding the columns of the
814 named table(s). If no columns were found, or an error occurred, this pointer
817 THE CALLING FUNCTION IS RESPONSIBLE FOR DELETING THE
{\it wxDbColInf
} MEMORY WHEN IT IS
820 \normalbox{ALL column bindings associated with this wxDb instance are unbound
821 by this function, including those used by any wxDbTable instances that use
822 this wxDb instance. This function should use its own wxDb instance
823 to avoid undesired unbinding of columns.
}
827 \helpref{wxDbColInf
}{wxdbcolinf
}
832 wxChar *tableList
[] =
{"PARTS",
0};
833 wxDbColInf *colInf = pDb->GetColumns(tableList);
836 // Use the column inf
838 // Destroy the memory
843 \membersection{wxDb::GetData
}\label{wxdbgetdata
}
845 \func{bool
}{GetData
}{\param{UWORD
}{ colNumber
},
\param{SWORD
}{ cType
},
846 \param{PTR
}{ pData
},
\param{SDWORD
}{ maxLen
},
\param{SDWORD FAR *
}{ cbReturned
} }
848 Used to retrieve result set data without binding column values to memory
849 variables (i.e. not using a wxDbTable instance to access table data).
851 \wxheading{Parameters
}
853 \docparam{colNumber
}{Ordinal number of the desired column in the result set to be
855 \docparam{cType
}{The C data type that is to be returned. See a partial list
856 in
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}}
857 \docparam{pData
}{Memory buffer which will hold the data returned by the call
859 \docparam{maxLen
}{Maximum size of the buffer
{\it 'pData'
} in characters.
860 NOTE: Not UNICODE safe. If this is a numeric field, a value of
0 may be
861 passed for this parameter, as the API knows the size of the expected return
863 \docparam{cbReturned
}{Pointer to the buffer containing the length of the
864 actual data returned. If this value comes back as SQL
\_NULL\_DATA, then the
865 \helpref{wxDb::GetData
}{wxdbgetdata
} call has failed.
}
869 \helpref{wxDb::GetNext
}{wxdbgetnext
},
\helpref{wxDb::ExecSql
}{wxdbexecsql
}
877 sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
878 PART_RECID =
1450 AND REQUIRED_QTY > PICKED_QTY";
881 if (!pDb->ExecSql(sqlStmt.c_str()))
887 // Request the first row of the result set
894 // Read column
#1 of the row returned by the call to ::GetNext()
895 // and return the value in 'reqQty'
896 if (!pDb->GetData(
1, SQL_C_ULONG, &reqQty,
0, &cb))
902 // Check for a NULL result
903 if (cb == SQL_NULL_DATA)
909 When requesting multiple columns to be returned from the result set (for example, the SQL query
910 requested
3 columns be returned), the calls to this function must request the columns in ordinal
911 sequence (
1,
2,
3 or
1,
3 or
2,
3).
913 \membersection{wxDb::GetDatabaseName
}\label{wxdbgetdatabasename
}
915 \func{const wxChar *
}{GetDatabaseName
}{\void}
917 Returns the name of the database engine.
919 \membersection{wxDb::GetDatasourceName
}\label{wxdbgetdatasourcename
}
921 \func{const wxString \&
}{GetDatasourceName
}{\void}
923 Returns the ODBC datasource name.
925 \membersection{wxDb::GetHDBC
}\label{wxdbgethdbc
}
927 \func{HDBC
}{GetHDBC
}{\void}
929 Returns the ODBC handle to the database connection.
931 \membersection{wxDb::GetHENV
}\label{wxdbgethenv
}
933 \func{HENV
}{GetHENV
}{\void}
935 Returns the ODBC environment handle.
937 \membersection{wxDb::GetHSTMT
}\label{wxdbgethstmt
}
939 \func{HSTMT
}{GetHSTMT
}{\void}
941 Returns the ODBC statement handle associated with this database connection.
943 \membersection{wxDb::GetKeyFields
}\label{wxdbgetkeyfields
}
945 \func{int
}{GetKeyFields
}{\param{const wxString \&
}{tableName
},
\param{wxDbColInf *
}{colInf
},
\param{UWORD
}{numColumns
}}
947 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.
949 This function is primarily for use by the
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
} function, but may be called if desired from the client application.
951 \wxheading{Parameters
}
953 \docparam{tableName
}{Name of the table for which the columns will be evaluated as to their inclusion in any indexes.
}
954 \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.
}
955 \docparam{numColumns
}{Number of columns defined in the instance of colInf.
}
957 \wxheading{Return value
}
959 Currently always returns true.
963 \helpref{wxDbColInf
}{wxdbcolinf
},
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
}
965 \membersection{wxDb::GetNext
}\label{wxdbgetnext
}
967 \func{bool
}{GetNext
}{\void}
969 Called after executing a query, this function requests the next row
970 in the result set after the current position of the cursor.
974 \helpref{wxDb::ExecSql
}{wxdbexecsql
},
\helpref{wxDb::GetData
}{wxdbgetdata
}
976 \membersection{wxDb::GetNextError
}\label{wxdbgetnexterror
}
978 \func{bool
}{GetNextError
}{\param{HENV
}{ aHenv
},
979 \param{HDBC
}{ aHdbc = SQL
\_NULL\_HDBC},
\param{HSTMT
}{ aHstmt = SQL
\_NULL\_HSTMT}}
981 \wxheading{Parameters
}
983 \docparam{aHenv
}{A handle to the ODBC environment.
}
984 \docparam{aHdbc
}{{\it OPTIONAL.
} A handle to the ODBC connection. Pass this
985 in if the ODBC function call that failed required a hdbc or hstmt argument.
}
986 \docparam{AHstmt
}{{\it OPTIONAL.
}A handle to the ODBC statement being executed
987 against. Pass this in if the ODBC function call that failed requires a
993 if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
995 return(db.GetNextError(db.henv, db.hdbc, hstmt));
1001 \helpref{wxDb::DispNextError
}{wxdbdispnexterror
},
1002 \helpref{wxDb::DispAllErrors
}{wxdbdispallerrors
}
1005 \membersection{wxDb::GetPassword
}\label{wxdbgetpassword
}
1007 \func{const wxString \&
}{GetPassword
}{\void}
1009 Returns the password used to establish this connection to the datasource.
1012 \membersection{wxDb::GetTableCount
}\label{wxdbgettablecount
}
1014 \func{int
}{GetTableCount
}{\void}
1016 Returns the number of wxDbTable() instances currently using this datasource
1020 \membersection{wxDb::GetUsername
}\label{wxdbgetusername
}
1022 \func{const wxString \&
}{GetUsername
}{\void}
1024 Returns the user name (uid) used to establish this connection to the
1028 \membersection{wxDb::Grant
}\label{wxdbgrant
}
1030 \func{bool
}{Grant
}{\param{int
}{privileges
},
\param{const wxString \&
}{tableName
},
1031 \param{const wxString \&
}{userList = "PUBLIC"
}}
1033 Use this member function to GRANT privileges to users for accessing tables in
1036 \wxheading{Parameters
}
1038 \docparam{privileges
}{Use this argument to select which privileges you want to
1039 grant. Pass DB
\_GRANT\_ALL to grant all privileges. To grant individual
1040 privileges pass one or more of the following OR'd together:
}
1047 DB_GRANT_ALL = DB_GRANT_SELECT | DB_GRANT_INSERT |
1048 DB_GRANT_UPDATE | DB_GRANT_DELETE
1051 \docparam{tableName
}{The name of the table you wish to grant privileges on.
}
1052 \docparam{userList
}{{\it OPTIONAL.
} A comma delimited list of users to grant the privileges to. If this argument is not passed in, the privileges will be given to the general PUBLIC.
}
1056 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.
1058 The currently logged in user must have sufficient grantor privileges for this
1059 function to be able to successfully grant the indicated privileges.
1064 db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
1067 \membersection{wxDb::IsFwdOnlyCursors
}\label{wxdbisfwdonlycursors
}
1069 \func{bool
}{IsFwdOnlyCursors
}{\void}
1071 This setting indicates whether this database connection was created
1072 as being capable of using only forward scrolling cursors.
1074 This function does NOT indicate if the ODBC driver or datasource supports
1075 backward scrolling cursors. There is no standard way of detecting if the
1076 driver or datasource can support backward scrolling cursors.
1078 If a wxDb instance was created as being capable of only forward scrolling
1079 cursors, then even if the datasource and ODBC driver support backward
1080 scrolling cursors, tables using this database connection would only be able
1081 to use forward scrolling cursors.
1083 The default setting of whether a wxDb connection to a database allows
1084 forward-only or also backward scrolling cursors is defined in setup.h by the
1085 value of wxODBC
\_FWD\_ONLY\_CURSORS. This default setting can be overridden
1086 when the wxDb connection is initially created (see
1087 \helpref{wxDb constructor
}{wxdbctor
} and
\helpref{wxDbGetConnection
}{wxdbfunctions
}).
1089 \wxheading{Return value
}
1091 Returns true if this datasource connection is defined as using only forward
1092 scrolling cursors, or false if the connection is defined as being allowed to
1093 use backward scrolling cursors and their associated functions (see note above).
1097 Added as of wxWidgets v2.4 release, this function is a renamed version of
1098 wxDb::FwdOnlyCursors() to match the normal wxWidgets naming conventions for
1099 class member functions.
1101 This function is not available in versions prior to v2.4. You should
1102 use
\helpref{wxDb::FwdOnlyCursors
}{wxdbfwdonlycursors
} for wxWidgets
1103 versions prior to
2.4.
1105 \wxheading{See also
}
1107 \helpref{wxDb constructor
}{wxdbctor
},
\helpref{wxDbGetConnection
}{wxdbfunctions
}
1109 \membersection{wxDb::IsOpen
}\label{wxdbisopen
}
1111 \func{bool
}{IsOpen
}{\void}
1113 Indicates whether the database connection to the datasource is currently
1118 This function may indicate that the database connection is open, even if
1119 the call to
\helpref{wxDb::Open
}{wxdbopen
} may have failed to fully
1120 initialize the connection correctly. The connection to the database
1121 {\it is
} open and can be used via the direct SQL commands, if this
1122 function returns true. Other functions which depend on the
1123 \helpref{wxDb::Open
}{wxdbopen
} to have completed correctly may not function
1124 as expected. The return result from
\helpref{wxDb::Open
}{wxdbopen
} is the
1125 only way to know if complete initialization of this wxDb connection was
1126 successful or not. See
\helpref{wxDb::Open
}{wxdbopen
} for more details on
1127 partial failures to open a connection instance.
1129 \membersection{wxDb::LogError
}\label{wxdblogerror
}
1131 \func{void
}{LogError
}{\param{const wxString \&
}{errMsg
} \param{const wxString \&
}{SQLState=""
}}
1133 \docparam{errMsg
}{Free-form text to display describing the error/text to be logged.
}
1134 \docparam{SQLState
}{{\it OPTIONAL.
} Native SQL state error. Default is
0.
}
1138 Calling this function will enter a log message in the error list maintained
1139 for the database connection. This log message is free form and can be
1140 anything the programmer wants to enter in the error list.
1142 If SQL logging is turned on, the call to this function will also log the
1143 text into the SQL log file.
1145 \wxheading{See also
}
1147 \helpref{wxDb::WriteSqlLog
}{wxdbwritesqllog
}
1149 \membersection{wxDb::ModifyColumn
}\label{wxdbmodifycolumn
}
1151 \func{void
}{ModifyColumn
}{\param{const wxString \&
}{tableName
} \param{const wxString \&
}{ColumnName
}
1152 \param{int
}{dataType
} \param{ULONG
}{columnLength=
0} \param{const wxString \&
}{optionalParam=""
}}
1154 Used to change certain properties of a column such as the length, or whether a column
1155 allows NULLs or not.
1157 \docparam{tableName
}{Name of the table that the column to be modified is in.
}
1158 \docparam{columnName
}{Name of the column to be modified. NOTE: Name of column cannot
1159 be changed with this function.
}
1160 \docparam{dataType
}{Any one of DB
\_DATA\_TYPE\_VARCHAR, DB
\_DATA\_TYPE\_INTEGER,
1161 DB
\_DATA\_TYPE\_FLOAT, DB
\_DATA\_TYPE\_DATE.
}
1162 \docparam{columnLength
}{New size of the column. Valid only for DB
\_DATA\_TYPE\_VARCHAR
1163 dataType fields. Default is
0.
}
1164 \docparam{optionalParam
}{Default is "".
}
1168 Cannot be used to modify the precision of a numeric column, therefore 'columnLength'
1169 is ignored unless the dataType is DB
\_DATA\_TYPE\_VARCHAR.
1171 Some datasources do not allow certain properties of a column to be changed if any rows
1172 currently have data stored in that column. Those datasources that do allow columns
1173 to be changed with data in the rows many handle truncation and/or expansion in
1174 different ways. Please refer to the reference material for the datasource being
1175 used for behavioral descriptions.
1180 ok = pDb->ModifyColumn("CONTACTS", "ADDRESS2",
1181 DB_, colDefs
[j
].SzDataObj,
1186 \membersection{wxDb::Open
}\label{wxdbopen
}
1188 \func{bool
}{Open
}{\param{const wxString \&
}{Dsn
},
\param{const wxString \&
}{Uid
},
1189 \param{const wxString \&
}{AuthStr
},
\param{bool
}{failOnDataTypeUnsupported
}}
1191 \func{bool
}{Open
}{\param{const wxString \&
}{inConnectStr
},
1192 \param{bool
}{failOnDataTypeUnsupported
}}
1194 \func{bool
}{Open
}{\param{wxDbConnectInf *
}{dbConnectInf
},
1195 \param{bool
}{failOnDataTypeUnsupported
}}
1197 \func{bool
}{Open
}{\param{wxDb *
}{copyDb
}}
1199 Opens a connection to the datasource, sets certain behaviors of the datasource
1200 to confirm to the accepted behaviors (e.g. cursor position maintained on
1201 commits), and queries the datasource for its representations of the basic
1202 datatypes to determine the form in which the data going to/from columns in
1203 the data tables are to be handled.
1205 The second form of this function, which accepts a "wxDb *" as a parameter,
1206 can be used to avoid the overhead (execution time, database load, network
1207 traffic) which are needed to determine the data types and representations
1208 of data that are necessary for cross-datasource support by these classes.
1210 Normally the first form of the wxDb::Open() function will open the connection
1211 and then send a series of queries to the datasource asking it for its
1212 representation of data types, and all the features it supports. If one
1213 connection to the datasource has already been made previously, the information
1214 gathered when that connection was created can just be copied to any new
1215 connections to the same datasource by passing a pointer to the first
1216 connection in as a parameter to the wxDb::Open() function. Note that this
1217 new connection created from the first connections information will use the
1218 same Dsn/Uid/AuthStr as the first connection used.
1220 \wxheading{Parameters
}
1222 \docparam{Dsn
}{datasource name. The name of the ODBC datasource as
1223 assigned when the datasource is initially set up through the ODBC data
1225 \docparam{Uid
}{User ID. The name (ID) of the user you wish to connect as
1226 to the datasource. The user name (ID) determines what objects you
1227 have access to in the datasource and what datasource privileges you have.
1228 Privileges include being able to create new objects, update objects, delete
1229 objects and so on. Users and privileges are normally administered by the
1230 database administrator.
}
1231 \docparam{AuthStr
}{The password associated with the Uid.
}
1232 \docparam{failOnDataTypeUnsupporte
}{As part of connecting to a database, the
1233 wxDb::Open() function will query the database to find out the native types
1234 that it supports. With some databases, some data types may not be supported,
1235 or not sufficiently supported, for use with the wxODBC classes. Normally
1236 a program should fail in this case, so as not to try to use a data type
1237 that is not supported. This parameter allows the programmer to override the
1238 failure if they wish and continue on using the connection.
}
1239 \docparam{dbConnectInf
}{Contains a DSN, Uid, Password, or a connection string
1240 to be used in opening a new connection to the database. If a connection
1241 string is present, then the connection string will be used. If there is no
1242 connection string present, then the DSN, Uid, and Password are used.
}
1243 \docparam{inConnectStr
}{A valid ODBC connection string used to connect to a
1245 \docparam{copyDb
}{Already completely configured and opened datasource
1246 connection from which all Dsn, Uid, AuthStr, connection string, and data
1247 typing information is to be copied from for use by this datasource
1248 connection. If 'copyDb' used a connection string to create its connection
1249 originally, then the connection being made by this call to wxDb::Open() will
1250 use that same connection string.
}
1254 After a wxDb instance is created, it must then be opened. When opening a
1255 datasource, there must be three pieces of information passed. The data
1256 source name, user name (ID) and the password for the user. No database
1257 activity on the datasource can be performed until the connection is opened.
1258 This is normally done at program startup and the datasource remains
1259 open for the duration of the program/module run.
1261 It is possible to have connections to multiple datasources open at the same
1262 time to support distributed database connections by having separate instances
1263 of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.
1265 If this function returns a value of false, it does not necessarily mean that
1266 the connection to the datasource was not opened. It may mean that some
1267 portion of the initialization of the connection failed (such as a datatype not
1268 being able to be determined how the datasource represents it). To determine
1269 if the connection to the database failed, use the
\helpref{wxDb::IsOpen
}{wxdbisopen
}
1270 function after receiving a false result back from this function to determine if
1271 the connection was opened or not. If this function returns false, but
\helpref{wxDb::IsOpen
}{wxdbisopen
}
1272 returns true, then direct SQL commands may be passed to the database
1273 connection and can be successfully executed, but use of the datatypes (such as
1274 by a wxDbTable instance) that are normally determined during open will not be
1277 \normalbox{The
{\it Dsn
},
{\it Uid
}, and
{\it AuthStr
} string pointers that are passed in
1278 are copied. NOT the strings themselves, only the pointers. The calling routine
1279 must maintain the memory for these three strings for the life of the wxDb instance.
}
1284 wxDb sampleDB(DbConnectInf.GetHenv());
1285 if (!sampleDB.Open("Oracle
7.1 HP/UX", "gtasker", "myPassword"))
1287 if (sampleDb.IsOpen())
1289 // Connection is open, but the initialization of
1290 // datatypes and parameter settings failed
1294 // Error opening datasource
1299 \membersection{wxDb::RollbackTrans
}\label{wxdbrollbacktrans
}
1301 \func{bool
}{RollbackTrans
}{\void}
1303 Function to "undo" changes made to the database. After an insert/update/delete, the operation may be "undone" by issuing this command any time before a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} is called on the database connection.
1307 Transactions begin implicitly as soon as you make a change to the database. The
1308 transaction continues until either a commit or rollback is executed. Calling
1309 wxDb::RollbackTrans() will result in ALL changes done using this database
1310 connection that have not already been committed to be "undone" back to the last
1311 commit/rollback that was successfully executed.
1313 \normalbox{Calling this member function rolls back ALL open (uncommitted)
1314 transactions on this ODBC connection, including all wxDbTable instances that
1315 use this connection.
}
1317 \wxheading{See also
}
1319 \helpref{wxDb::CommitTrans
}{wxdbcommittrans
} for a special note on cursors
1321 \membersection{wxDb::SetDebugErrorMessages
}\label{wxdbsetdebugerrormessages
}
1323 \func{void
}{SetDebugErrorMessages
}{\param{bool
}{state
}}
1325 \docparam{state
}{Either true (debug messages are logged) or false (debug
1326 messages are not logged).
}
1330 Turns on/off debug error messages from the ODBC class library. When
1331 this function is passed true, errors are reported to the user/logged automatically
1332 in a text or pop-up dialog when an ODBC error occurs. When passed false,
1333 errors are silently handled.
1335 When compiled in release mode (FINAL=
1), this setting has no affect.
1337 \wxheading{See also
}
1339 \helpref{wxDb constructor
}{wxdbctor
}
1341 \membersection{wxDb::SetSqlLogging
}\label{wxdbsetsqllogging
}
1343 \func{bool
}{SetSqlLogging
}{\param{wxDbSqlLogState
}{ state
},
\param{const wxString \&
}{filename = SQL
\_LOG\_FILENAME},
\param{bool
}{ append = false
}}
1345 \wxheading{Parameters
}
1347 \docparam{state
}{Either sqlLogOFF or sqlLogON (see
\helpref{enum wxDbSqlLogState
}{wxdbcolfor
}). Turns logging of SQL commands sent to the datasource OFF or ON.
}
1348 \docparam{filename
}{{\it OPTIONAL
}. Name of the file to which the log text is to be written. Default is SQL
\_LOG\_FILENAME.
}
1349 \docparam{append
}{{\it OPTIONAL
}. Whether the file is appended to or overwritten. Default is false.
}
1353 When called with
{\it sqlLogON
}, all commands sent to the datasource engine are logged to the file specified by
{\it filename
}. Logging is done by embedded
\helpref{wxDb::WriteSqlLog
}{wxdbwritesqllog
} calls in the database member functions, or may be manually logged by adding calls to
\helpref{wxDb::WriteSqlLog
}{wxdbwritesqllog
} in your own source code.
1355 When called with
{\it sqlLogOFF
}, the logging file is closed, and any calls to
\helpref{wxDb::WriteSqlLog
}{wxdbwritesqllog
} are ignored.
1357 \membersection{wxDb::SQLColumnName
}\label{wxdbsqlcolumnname
}
1359 \func{const wxString
}{SQLColumnName
}{\param{const char *
}{ colName
}}
1361 Returns the column name in a form ready for use in SQL statements.
1362 In most cases, the column name is returned verbatim. But some databases
1363 (e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which
1364 must be specially quoted. For example, if the datasource allows spaces
1365 in the column name, the returned string will have the correct enclosing
1366 marks around the name to allow it to be properly included in a SQL statement
1367 for the DBMS that is currently connected to with this connection.
1369 \wxheading{Parameters
}
1371 \docparam{colName
}{Native name of the column in the table that is to be
1372 evaluated to determine if any special quoting marks needed to be added to it
1373 before including the column name in a SQL statement
}
1375 \wxheading{See also
}
1377 \helpref{wxDb::SQLTableName
}{wxdbsqltablename
}
1379 \membersection{wxDb::SQLTableName
}\label{wxdbsqltablename
}
1381 \func{const wxString
}{SQLTableName
}{\param{const char *
}{ tableName
}}
1383 Returns the table name in a form ready for use in SQL statements.
1384 In most cases, the table name is returned verbatim. But some databases
1385 (e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which
1386 must be specially quoted. For example, if the datasource allows spaces
1387 in the table name, the returned string will have the correct enclosing
1388 marks around the name to allow it to be properly included in a SQL statement
1389 for the data source that is currently connected to with this connection.
1391 \wxheading{Parameters
}
1393 \docparam{tableName
}{Native name of the table that is to be evaluated to
1394 determine if any special quoting marks needed to be added to it
1395 before including the table name in a SQL statement
}
1397 \wxheading{See also
}
1399 \helpref{wxDb::SQLColumnName
}{wxdbsqlcolumnname
}
1401 \membersection{wxDb::TableExists
}\label{wxdbtableexists
}
1403 \func{bool
}{TableExists
}{\param{const wxString \&
}{tableName
},
\param{const wxChar *
}{userID=NULL
},
\param{const wxString \&
}{path=""
}}
1405 Checks the ODBC datasource for the existence of a table. If a
{\it userID
}
1406 is specified, then the table must be accessible by that user (user must have
1407 at least minimal privileges to the table).
1409 \wxheading{Parameters
}
1411 \docparam{tableName
}{Name of the table to check for the existence of.
}
1412 \docparam{userID
}{Owner of the table (also referred to as schema). Specify a userID when the datasource you are connected
1413 to allows multiple unique tables with the same name to be owned by different users.
{\it userID
}
1414 is evaluated as follows:
}
1417 userID == NULL ... UserID is ignored (DEFAULT)
1418 userID == "" ... UserID set equal to 'this->uid'
1419 userID != "" ... UserID set equal to 'userID'
1424 {\it tableName
} may refer to a table, view, alias or synonym.
1426 This function does not indicate whether or not the user has privileges to query or perform other functions on the table. Use the
\helpref{wxDb::TablePrivileges
}{wxdbtableprivileges
} to determine if the user has sufficient privileges or not.
1428 \wxheading{See also
}
1430 \helpref{wxDb::TablePrivileges
}{wxdbtableprivileges
}
1432 \membersection{wxDb::TablePrivileges
}\label{wxdbtableprivileges
}
1434 \func{bool
}{TablePrivileges
}{\param{const wxString \&
}{tableName
},
\param{const wxString \&
}{priv
},
1435 \param{const wxChar *
}{userID=NULL
},
\param{const wxChar *
}{schema=NULL
},
1436 \param{const wxString \&
}{path=""
}}
1438 Checks the ODBC datasource for the existence of a table. If a
{\it userID
}
1439 is specified, then the table must be accessible by that user (user must have
1440 at least minimal privileges to the table).
1442 \wxheading{Parameters
}
1444 \docparam{tableName
}{Name of the table on which to check privileges.
1445 {\it tableName
} may refer to a table, view, alias or synonym.
}
1446 \docparam{priv
}{The table privilege being evaluated. May be one of the
1447 following (or a datasource specific privilege):
}
1450 SELECT : The connected user is permitted to retrieve data for
1451 one or more columns of the table.
1453 INSERT : The connected user is permitted to insert new rows
1454 containing data for one or more columns into the
1457 UPDATE : The connected user is permitted to update the data in
1458 one or more columns of the table.
1460 DELETE : The connected user is permitted to delete rows of
1461 data from the table.
1463 REFERENCES : Is the connected user permitted to refer to one or
1464 more columns of the table within a constraint (for
1465 example, a unique, referential, or table check
1469 \docparam{userID
}{{\it OPTIONAL.
} User for which to determine if the privilege
1470 specified to be checked is granted or not. Default is "".
1471 {\it userID
} is evaluated as follows:
}
1474 userID == NULL ... NOT ALLOWED!
1475 userID == "" ... UserID set equal to 'this->uid'
1476 userID != "" ... UserID set equal to 'userID'
1479 \docparam{schema
}{{\it OPTIONAL.
} Owner of the table. Specify a userID when the datasource
1480 you are connected to allows multiple unique tables with the same name to be
1481 owned by different users. Specifying the table owner makes determination of the
1482 users privileges MUCH faster. Default is NULL.
{\it userID
} is
1483 evaluated as follows:
}
1486 schema == NULL ... Any owner (DEFAULT)
1487 schema == "" ... Owned by 'this->uid'
1488 schema != "" ... Owned by userID specified in 'schema'
1491 \docparam{path
}{{\it OPTIONAL.
} Path to the table. Default is "".
1496 The scope of privilege allowed to the connected user by a given table
1497 privilege is datasource dependent.
1499 For example, the privilege UPDATE might allow the connected user to update
1500 all columns in a table on one datasource, but only those columns for
1501 which the grantor (the user that granted the connected user) has the UPDATE
1502 privilege on another datasource.
1504 Looking up a user's privileges to a table can be time consuming depending on the
1505 datasource and ODBC driver. This time can be minimized by passing a
{\it schema
}
1506 as a parameter. With some datasources/drivers, the difference can be several
1507 seconds of time difference.
1510 \membersection{wxDb::TranslateSqlState
}\label{wxdbtranslatesqlstate
}
1512 \func{int
}{TranslateSqlState
}{\param{const wxString \&
}{SQLState
}}
1514 Converts an ODBC sqlstate to an internal error code.
1516 \wxheading{Parameters
}
1518 \docparam{SQLState
}{State to be converted.
}
1520 \wxheading{Return value
}
1522 Returns the internal class DB
\_ERR code. See
\helpref{wxDb::DB
\_STATUS}{wxdb
} definition.
1524 \membersection{wxDb::WriteSqlLog
}\label{wxdbwritesqllog
}
1526 \func{bool
}{WriteSqlLog
}{\param{const wxString \&
}{logMsg
}}
1528 \wxheading{Parameters
}
1530 \docparam{logMsg
}{Free form string to be written to the log file.
}
1534 Very useful debugging tool that may be turned on/off during run time (see
1535 (see
\helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
} for details on
1536 turning logging on/off). The passed in string
{\it logMsg
} will be written to
1537 a log file if SQL logging is turned on.
1539 \wxheading{Return value
}
1541 If SQL logging is off when a call to WriteSqlLog() is made, or there is a
1542 failure to write the log message to the log file, the function returns
1543 false without performing the requested log, otherwise true is returned.
1545 \wxheading{See also
}
1547 \helpref{wxDb::SetSqlLogging
}{wxdbsetsqllogging
}
1549 \section{\class{wxDbColDataPtr
}}\label{wxdbcoldataptr
}
1551 Pointer to dynamic column definitions for use with a wxDbTable instance.
1552 Currently there are no member functions for this class.
1554 See the
\helpref{database classes overview
}{odbcoverview
} for
1555 an introduction to using the ODBC classes.
1563 \section{\class{wxDbColDef
}}\label{wxdbcoldef
}
1565 This class is used to hold information about the columns bound to an
1566 instance of a wxDbTable object.
1568 Each instance of this class describes one column in the wxDbTable
1569 object. When calling the
\helpref{wxDb constructor
}{wxdbctor
}, a
1570 parameter passed in indicates the number of columns that will be defined for
1571 the wxDbTable object. The constructor uses this information to allocate
1572 adequate memory for all of the column descriptions in your wxDbTable object.
1573 Private member wxDbTable::colDefs is a pointer to this chunk of memory
1574 maintained by the wxDbTable class (and can be retrieved using the
1575 \helpref{wxDbTable::GetColDefs
}{wxdbtablegetcoldefs
} function).
1576 To access the nth column definition of your wxDbTable object, just reference
1577 wxDbColDefs element
[n -
1].
1579 Typically,
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
} is used to
1580 populate an array of these data structures for the wxDbTable instance.
1582 Currently there are no accessor functions for this class, so all members are
1586 wxChar ColName
[DB_MAX_COLUMN_NAME_LEN+
1]; // Column Name
1587 int DbDataType; - Logical Data Type;
1588 e.g. DB_DATA_TYPE_INTEGER
1589 SWORD SqlCtype; - C data type; e.g. SQL_C_LONG
1590 void *PtrDataObj; - Address of the data object
1591 int SzDataObj; - Size, in bytes, of the data object
1592 bool KeyField; - Is column part of the PRIMARY KEY for the
1593 table? -- Date fields should NOT be
1595 bool Updateable; - Column is updateable?
1596 bool InsertAllowed; - Column included in INSERT statements?
1597 bool DerivedCol; - Column is a derived value?
1598 SDWORD CbValue; - !!!Internal use only!!!
1599 bool Null; - NOT FULLY IMPLEMENTED
1600 Allows NULL values in Inserts and Updates
1603 \wxheading{See also
}
1605 \helpref{database classes overview
}{odbcoverview
},
1606 \helpref{wxDbTable::GetColDefs
}{wxdbtablegetcoldefs
},
\helpref{wxDb constructor
}{wxdbctor
}
1608 \membersection{wxDbColDef::Initialize
}\label{wxdbcoldefinitialize
}
1610 Simply initializes all member variables to a cleared state. Called by
1611 the constructor automatically.
1613 \section{\class{wxDbColFor
}}\label{wxdbcolfor
}
1615 Beginning support for handling international formatting specifically on dates
1619 wxString s_Field; // Formated String for Output
1620 wxString s_Format
[7]; // Formated Objects - TIMESTAMP has
1622 wxString s_Amount
[7]; // Formated Objects - amount of
1623 things that can be formatted
1624 int i_Amount
[7]; // Formated Objects -
1625 TT MM YYYY HH MM SS m
1626 int i_Nation; //
0 = timestamp
1631 int i_dbDataType; // conversion of the 'sqlDataType'
1632 to the generic data type used by
1634 SWORD i_sqlDataType;
1637 The constructor for this class initializes all the values to zero or NULL.
1639 The destructor does nothing at this time.
1641 Only one function is provided with this class currently.
1643 See the
\helpref{database classes overview
}{odbcoverview
} for
1644 an introduction to using the ODBC classes.
1646 \membersection{wxDbColFor::Format
}\label{wxdbcolforformat
}
1648 \func{int
}{Format
}{\param{int
}{Nation
},
\param{int
}{dbDataType
},
1649 \param{SWORD
}{sqlDataType
},
\param{short
}{columnSize
},
1650 \param{short
}{decimalDigits
}}\label{wxdbcolforformat
}
1652 Work in progress, and should be inter-related with wxLocale eventually.
1654 \membersection{wxDbColFor::Initialize
}\label{wxdbcolforinitialize
}
1656 Simply initializes all member variables to a cleared state. Called by
1657 the constructor automatically.
1659 \section{\class{wxDbColInf
}}\label{wxdbcolinf
}
1661 Used with the
\helpref{wxDb::GetColumns
}{wxdbgetcolumns
} functions for obtaining all retrievable information about a column's definition.
1664 wxChar catalog
[128+
1];
1665 wxChar schema
[128+
1];
1666 wxChar tableName
[DB_MAX_TABLE_NAME_LEN+
1];
1667 wxChar colName
[DB_MAX_COLUMN_NAME_LEN+
1];
1669 wxChar typeName
[128+
1];
1672 short decimalDigits;
1675 wxChar remarks
[254+
1];
1676 int dbDataType; // conversion of the 'sqlDataType'
1677 // to the generic data type used by
1679 int PkCol; // Primary key column
1682 2 = Second Key, etc...
1683 wxChar PkTableName
[DB_MAX_TABLE_NAME_LEN+
1];
1684 // Tables that use this PKey as a FKey
1685 int FkCol; // Foreign key column
1688 2 = Second Key, etc...
1689 wxChar FkTableName
[DB_MAX_TABLE_NAME_LEN+
1];
1690 // Foreign key table name
1691 wxDbColFor *pColFor; // How should this column be formatted
1694 The constructor for this class initializes all the values to zero, "", or NULL.
1696 The destructor for this class takes care of deleting the pColFor member if
1699 See the
\helpref{database classes overview
}{odbcoverview
} for
1700 an introduction to using the ODBC classes.
1702 \membersection{wxDbColInf::Initialize
}\label{wxdbcolinfinitialize
}
1704 Simply initializes all member variables to a cleared state. Called by
1705 the constructor automatically.
1707 \section{\class{wxDbConnectInf
}}\label{wxdbconnectinf
}
1709 This class is used for holding the data necessary for connecting to the ODBC
1710 datasource. That information includes: SQL environment handle, datasource
1711 name, user ID, password and default directory path (used with dBase). Other
1712 optional fields held in this class are and file type, both for future
1713 functions planned to be added for creating/manipulating datasource definitions.
1715 \membersection{wxDbConnectInf::wxDbConnectInf
}\label{wxdbconnectinfctor
}
1717 \func{}{wxDbConnectInf
}{\void}
1719 Default constructor.
1721 \func{}{wxDbConnectInf
}{\param{HENV
}{henv
},
\param{const wxString \&
}{dsn
},
1722 \param{const wxString \&
}{userID=""
},
\param{const wxString \&
}{password
},
1723 \param{const wxString \&
}{defaultDir=""
},
\param{const wxString \&
}{description=""
},
1724 \param{const wxString \&
}{fileType=""
}}
1726 Constructor which allows initial settings of all the classes member variables.
1728 See the special note below on the henv parameter for forcing this constructor
1729 to create a SQL environment handle automatically, rather than needing to pass
1730 one in to the function.
1732 \wxheading{Parameters
}
1734 \docparam{henv
}{Environment handle used for this connection. See
\rtfsp
1735 \helpref{wxDConnectInf::AllocHenv
}{wxdbconnectinfallochenv
} for how to create
1736 an SQL environment handle. NOTE: Passing in a NULL for this parameter will
1737 inform the constructor that it should create its own SQL environment handle.
1738 If NULL is passed for this parameter, the constructor will call
\rtfsp
1739 \helpref{wxDConnectInf::AllocHenv
}{wxdbconnectinfallochenv
} internally. A
1740 flag is set internally also to indicate that the HENV was created by the
1741 constructor so that when the default class destructor is called, the
1742 destructor will call
\helpref{wxDConnectInf::FreeHenv
}{wxdbconnectinffreehenv
}\rtfsp
1743 to free the environment handle automatically.
}
1744 \docparam{dsn
}{Name of the datasource to be used in creating wxDb instances
1745 for creating connection(s) to a datasource.
}
1746 \docparam{userID
}{{\it OPTIONAL
} Many datasources allow (or even require)
1747 use of a username to determine privileges that connecting user is allowed
1748 to have when accessing the datasource or the data tables. Default is "".
}
1749 \docparam{password
}{{\it OPTIONAL
} Password to be associated with the user
1750 ID specified in 'userID'. Default is "".
}
1751 \docparam{defaultDir
}{{\it OPTIONAL
} Used for datasources which require the
1752 path to where the data file is stored to be specified. dBase is one example
1753 of the type of datasource which requires this information. Default is "".
}
1754 \docparam{description
}{{\it OPTIONAL
} {\bf FUTURE USE
} Default is "".
}
1755 \docparam{fileType
}{{\it OPTIONAL
} {\bf FUTURE USE
} Default is "".
}
1759 It is strongly recommended that programs use the longer form of the
1760 constructor and allow the constructor to create the SQL environment handle
1761 automatically, and manage the destruction of the handle.
1766 wxDbConnectInf *DbConnectInf;
1768 DbConnectInf = new wxDbConnectInf(
0,"MY_DSN", "MY_USER", "MY_PASSWORD");
1770 ....the rest of the program
1772 delete DbConnectInf;
1775 \wxheading{See also
}
1777 \helpref{wxDConnectInf::AllocHenv
}{wxdbconnectinfallochenv
},
1778 \helpref{wxDConnectInf::FreeHenv
}{wxdbconnectinffreehenv
}
1780 \membersection{wxDbConnectInf::
\destruct{wxDbConnectInf
}}\label{wxdbconnectinfdestr
}
1782 \func{}{\destruct{wxDbConnectInf
}}{}
1784 Handles the default destruction of the instance of the class. If the long form
1785 of the
\helpref{wxDConnectInf
}{wxdbconnectinf
} was used, then this destructor
1786 also takes care of calling
\rtfsp
1787 \helpref{wxDConnectInf::FreeHenv
}{wxdbconnectinffreehenv
} to free the
1788 SQL environment handle.
1790 \membersection{wxDbConnectInf::AllocHenv
}\label{wxdbconnectinfallochenv
}
1792 \func{bool
}{AllocHenv
}{\void}
1794 Allocates a SQL environment handle that will be used to interface with
1799 This function can be automatically called by the long from of the
1800 \helpref{wxDbConnectInf
}{wxdbconnectinf
} constructor.
1802 \membersection{wxDbConnectInf::FreeHenv
}\label{wxdbconnectinffreehenv
}
1804 \func{void
}{FreeHenv
}{\void}
1806 Frees the SQL environment handle being managed by the instance of this class.
1810 If the SQL environment handle was created using the long form of the
\rtfsp
1811 \helpref{wxDbConnectInf
}{wxdbconnectinf
} constructor, then the flag indicating
1812 that the HENV should be destroyed when the classes destructor is called
1813 is reset to be false, so that any future handles created using the
\rtfsp
1814 \helpref{wxDbConnectInf::AllocHenv
}{wxdbconnectinfallochenv
} function
1815 must be manually released with a call to this function.
1817 \membersection{wxDbConnectInf::Initialize
}\label{wxdbconnectinfinitialize
}
1819 Simply initializes all member variables to a cleared state. Called by
1820 the constructor automatically.
1822 \membersection{wxDbConnectInf::GetAuthStr
}\label{wxdbconnectinfgetauthstr
}
1824 \func{const wxChar *
}{GetAuthStr
}{\void}
1826 Accessor function to return the password assigned for this class
1827 instance that will be used with the user ID.
1829 Synonymous with
\helpref{wxDbConnectInf::GetPassword
}{wxdbconnectinfgetpassword
}
1831 \membersection{wxDbConnectInf::GetDefaultDir
}\label{wxdbconnectinfgetdefaultdir
}
1833 \func{const wxChar *
}{GetDefaultDir
}{\void}
1835 Accessor function to return the default directory in which the datasource's data
1836 table is stored. This directory is only used for file based datasources like
1837 dBase. MS-Access does not require this to be set, as the path is set in the
1838 ODBC Administrator for MS-Access.
1840 \membersection{wxDbConnectInf::GetDescription
}\label{wxdbconnectinfgetdescription
}
1842 \func{const wxChar *
}{GetDescription
}{\void}
1844 Accessor function to return the description assigned for this class
1847 NOTE: Description is a FUTURE USE item and is unused currently.
1849 \membersection{wxDbConnectInf::GetDsn
}\label{wxdbconnectinfgetdsn
}
1851 \func{const wxChar *
}{GetDsn
}{\void}
1853 Accessor function to return the datasource name assigned for this class
1856 \membersection{wxDbConnectInf::GetFileType
}\label{wxdbconnectinfgetfiletype
}
1858 \func{const wxChar *
}{GetFileType
}{\void}
1860 Accessor function to return the filetype of the ODBC datasource assigned for
1861 this class instance.
1863 NOTE: FileType is a FUTURE USE item and is unused currently.
1865 \membersection{wxDbConnectInf::GetHenv
}\label{wxdbconnectinfgethenv
}
1867 \func{const HENV
}{GetHenv
}{\void}
1869 Accessor function to return the SQL environment handle being managed
1870 by this class instance.
1872 \membersection{wxDbConnectInf::GetPassword
}\label{wxdbconnectinfgetpassword
}
1874 \func{const wxChar *
}{GetPassword
}{\void}
1876 Accessor function to return the password assigned for this class
1877 instance that will be used with the user ID.
1879 Synonymous with
\helpref{wxDbConnectInf::GetAuthStr
}{wxdbconnectinfgetauthstr
}
1881 \membersection{wxDbConnectInf::GetUid
}\label{wxdbconnectinfgetuid
}
1883 \func{const wxChar *
}{GetUid
}{\void}
1885 Accessor function to return the user ID assigned for this class
1888 \membersection{wxDbConnectInf::GetUserID
}\label{wxdbconnectinfgetuserid
}
1890 \func{const wxChar *
}{GetUserID
}{\void}
1892 Accessor function to return the user ID assigned for this class
1895 \membersection{wxDbConnectInf::SetAuthStr
}\label{wxdbconnectinfsetauthstr
}
1897 \func{\void}{SetAuthStr
}{const wxString \&authstr
}
1899 Accessor function to assign the password for this class
1900 instance that will be used with the user ID.
1902 Synonymous with
\helpref{wxDbConnectInf::SetPassword
}{wxdbconnectinfsetpassword
}
1904 \membersection{wxDbConnectInf::SetDefaultDir
}\label{wxdbconnectinfsetdefaultdir
}
1906 \func{\void}{SetDefaultDir
}{const wxString \&defDir
}
1908 Accessor function to assign the default directory in which the datasource's data
1909 table is stored. This directory is only used for file based datasources like
1910 dBase. MS-Access does not require this to be set, as the path is set in the
1911 ODBC Administrator for MS-Access.
1913 \membersection{wxDbConnectInf::SetDescription
}\label{wxdbconnectinfsetdescription
}
1915 \func{\void}{SetDescription
}{const wxString \&desc
}
1917 Accessor function to assign the description assigned for this class
1920 NOTE: Description is a FUTURE USE item and is unused currently.
1922 \membersection{wxDbConnectInf::SetDsn
}\label{wxdbconnectinfsetdsn
}
1924 \func{\void}{SetDsn
}{const wxString \&dsn
}
1926 Accessor function to assign the datasource name for this class instance.
1928 \membersection{wxDbConnectInf::SetFileType
}\label{wxdbconnectinfsetfiletype
}
1930 \func{\void}{SetFileType
}{const wxString \&
}
1932 Accessor function to return the filetype of the ODBC datasource assigned for
1933 this class instance.
1935 NOTE: FileType is a FUTURE USE item and is unused currently.
1937 \membersection{wxDbConnectInf::SetHenv
}\label{wxdbconnectinfsethenv
}
1939 \func{void
}{SetHenv
}{\param{const HENV
}{henv
}}
1941 Accessor function to set the SQL environment handle for this class instance.
1943 \membersection{wxDbConnectInf::SetPassword
}\label{wxdbconnectinfsetpassword
}
1945 \func{\void}{SetPassword
}{const wxString \&password
}
1947 Accessor function to assign the password for this class
1948 instance that will be used with the user ID.
1950 Synonymous with
\helpref{wxDbConnectInf::SetAuthStr
}{wxdbconnectinfsetauthstr
}
1952 \membersection{wxDbConnectInf::SetUid
}\label{wxdbconnectinfsetuid
}
1954 \func{\void}{SetUid
}{const wxString \&uid
}
1956 Accessor function to set the user ID for this class instance.
1958 \membersection{wxDbConnectInf::SetUserID
}\label{wxdbconnectinfsetuserid
}
1960 \func{\void}{SetUserID
}{const wxString \&userID
}
1962 Accessor function to assign the user ID for this class instance.
1964 \section{\class{wxDbIdxDef
}}\label{wxdbidxdef
}
1966 Used in creation of non-primary indexes. Currently there are no member
1967 functions for this class.
1970 wxChar ColName
[DB_MAX_COLUMN_NAME_LEN+
1]
1972 bool Ascending // Is index maintained in
1976 There are no constructors/destructors as of this time, and no member functions.
1978 See the
\helpref{database classes overview
}{odbcoverview
} for
1979 an introduction to using the ODBC classes.
1982 \wxheading{Include files
}
1986 \section{\class{wxDbInf
}}\label{wxdbinf
}
1988 Contains information regarding the database connection (datasource name,
1989 number of tables, etc). A pointer to a wxDbTableInf is included in this
1990 class so a program can create a wxDbTableInf array instance to maintain all
1991 information about all tables in the datasource to have all the datasource's
1992 information in one memory structure.
1994 Primarily, this class is used internally by the wxWidgets ODBC classes.
1997 wxChar catalog
[128+
1];
1998 wxChar schema
[128+
1]; // typically means owner of table(s)
1999 int numTables; // How many tables does this
2001 wxDbTableInf *pTableInf; // Equals a new
2002 wxDbTableInf
[numTables
];
2005 The constructor for this class initializes all the values to zero, "", or NULL.
2007 The destructor for this class takes care of deleting the pTableInf member if
2010 See the
\helpref{database classes overview
}{odbcoverview
} for
2011 an introduction to using the ODBC classes.
2013 \membersection{wxDbInf::Initialize
}\label{wxdbinfinitialize
}
2015 Simply initializes all member variables to a cleared state. Called by
2016 the constructor automatically.
2018 \section{\class{wxDbTable
}}\label{wxdbtable
}
2020 A wxDbTable instance provides re-usable access to rows of data in
2021 a table contained within the associated ODBC datasource
2023 See the
\helpref{database classes overview
}{odbcoverview
} for
2024 an introduction to using the ODBC classes.
2026 \wxheading{Include files
}
2031 \latexignore{\rtfignore{\wxheading{Members
}}}
2032 \wxheading{Helper classes and data structures
}
2034 The following classes and structs are defined in dbtable.cpp/.h for use
2035 with the wxDbTable class.
2037 \begin{itemize
}\itemsep=
0pt
2038 \item \helpref{wxDbColDef
}{wxdbcoldef
}
2039 \item \helpref{wxDbColDataPtr
}{wxdbcoldataptr
}
2040 \item \helpref{wxDbIdxDef
}{wxdbidxdef
}
2043 \wxheading{Constants
}
2046 wxDB_DEFAULT_CURSOR Primary cursor normally used for cursor based
2049 wxDB_QUERY_ONLY Used to indicate whether a table that is opened
2050 is for query only, or if insert/update/deletes
2051 will be performed on the table. Less overhead
2052 (cursors and memory) are allocated for query
2053 only tables, plus read access times are faster
2054 with some datasources.
2056 wxDB_ROWID_LEN
[Oracle only
] - Used when CanUpdateByRowID()
2057 is true. Optimizes updates so they are faster
2058 by updating on the Oracle-specific ROWID column
2059 rather than some other index.
2062 wxDB_DISABLE_VIEW Use to indicate when a database view should not
2063 be if a table is normally set up to use a view.
2064 [Currently unsupported.
]
2069 \latexignore{\rtfignore{\wxheading{Members
}}}
2071 \membersection{wxDbTable::wxDbTable
}\label{wxdbtableconstr
}
2073 \func{}{wxDbTable
}{\param{wxDb *
}{pwxDb
},
\param{const wxString \&
}{tblName
},
2074 \param{const UWORD
}{numColumns
},
\param{const wxString \&
}{qryTblName = ""
},
2075 \param{bool
}{qryOnly = !wxDB
\_QUERY\_ONLY},
\param{const wxString \&
}{tblPath = ""
}}
2077 Default constructor.
2079 \wxheading{Parameters
}
2081 \docparam{pwxDb
}{Pointer to the wxDb instance to be used by this wxDbTable
2083 \docparam{tblName
}{The name of the table in the RDBMS.
}
2084 \docparam{numColumns
}{The number of columns in the table. (Do NOT include the ROWID
2085 column in the count if using Oracle).
}
2086 \docparam{qryTblName
}{{\it OPTIONAL
}. The name of the table or view to base
2087 your queries on. This argument allows you to specify a table/view other than
2088 the base table for this object to base your queries on. This allows you to
2089 query on a view for example, but all of the INSERT, UPDATE and DELETES will
2090 still be performed on the base table for this wxDbTable object. Basing your
2091 queries on a view can provide a substantial performance increase in cases where
2092 your queries involve many tables with multiple joins. Default is "".
}
2093 \docparam{qryOnly
}{{\it OPTIONAL
}. Indicates whether the table will be
2094 accessible for query purposes only, or should the table create the necessary
2095 cursors to be able to insert, update, and delete data from the table.
2096 Default is !wxDB
\_QUERY\_ONLY.
}
2097 \docparam{tblPath
}{{\it OPTIONAL
}. Some datasources (such as dBase)
2098 require a path to where the table is stored on the system. Default is "".
}
2100 \membersection{wxDbTable::wxDbTable
}\label{wxdbtabledestr
}
2102 \func{virtual
}{\destruct{wxDbTable
}}{}
2104 Virtual default destructor.
2106 \membersection{wxDbTable::BuildDeleteStmt
}\label{wxdbtablebuilddeletestmt
}
2108 \func{void
}{BuildDeleteStmt
}{\param{wxString \&
}{pSqlStmt
},
2109 \param{int
}{typeOfDel
},
\param{const wxString \&
}{pWhereClause=""
}}
2111 Constructs the full SQL statement that can be used to delete all rows matching
2112 the criteria in the pWhereClause.
2114 \wxheading{Parameters
}
2116 \docparam{pSqlStmt
}{Pointer to buffer for the SQL statement retrieved. To be
2117 sure you have adequate space allocated for the SQL statement, allocate
2118 DB
\_MAX\_STATEMENT\_LEN bytes.
}
2119 \docparam{typeOfDel
}{The type of delete statement being performed. Can be one
2120 of three values: DB
\_DEL\_KEYFIELDS, DB
\_DEL\_WHERE or DB
\_DEL\_MATCHING}
2121 \docparam{pWhereClause
}{{\it OPTIONAL
}. If the typeOfDel is DB
\_DEL\_WHERE,
2122 then you must also pass in a SQL WHERE clause in this argument. Default
2127 This member function constructs a SQL DELETE statement. This can be used for
2128 debugging purposes if you are having problems executing your SQL statement.
2130 WHERE and FROM clauses specified using
\helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2131 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
2134 \membersection{wxDbTable::BuildSelectStmt
}\label{wxdbtablebuildselectstmt
}
2136 \func{void
}{BuildSelectStmt
}{\param{wxString \&
}{pSqlStmt
},
2137 \param{int
}{typeOfSelect
},
\param{bool
}{distinct
}}
2139 Constructs the full SQL statement that can be used to select all rows matching
2140 the criteria in the pWhereClause. This function is called internally in the
2141 wxDbTable class whenever the function
\helpref{wxDbTable::Query
}{wxdbtablequery
}
2144 NOTE: Only the columns specified in
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
2145 statements are included in the list of columns returned by the SQL statement
2146 created by a call to this function.
2148 \wxheading{Parameters
}
2150 \docparam{pSqlStmt
}{Pointer to storage for the SQL statement retrieved. To be
2151 sure you have adequate space allocated for the SQL statement, allocate
2152 DB
\_MAX\_STATEMENT\_LEN bytes.
}
2153 \docparam{typeOfSelect
}{The type of select statement being performed. Can be
2154 one of four values: DB
\_SELECT\_KEYFIELDS, DB
\_SELECT\_WHERE, DB
\_SELECT\_MATCHING
2155 or DB
\_SELECT\_STATEMENT.
}
2156 \docparam{distinct
}{Whether to select distinct records only.
}
2160 This member function constructs a SQL SELECT statement. This can be used for
2161 debugging purposes if you are having problems executing your SQL statement.
2163 WHERE and FROM clauses specified using
2164 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2165 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
2168 \membersection{wxDbTable::BuildUpdateStmt
}\label{wxdbtablebuildupdatestmt
}
2170 \func{void
}{BuildUpdateStmt
}{\param{wxString \&
}{pSqlStmt
},
\param{int
}{typeOfUpd
},
2171 \param{const wxString \&
}{pWhereClause=""
}}
2173 Constructs the full SQL statement that can be used to update all rows matching
2174 the criteria in the pWhereClause.
2176 If typeOfUpdate is DB
\_UPD\_KEYFIELDS, then the current values in the bound columns
2177 are used to determine which row(s) in the table are to be updated. The
2178 exception to this is when a datasource supports ROW IDs (Oracle). The ROW ID
2179 column is used for efficiency purposes when available.
2181 NOTE: Only the columns specified in
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
2182 statements are included in the list of columns updated by the SQL statement
2183 created by a call to this function. Any column definitions that were defined
2184 as being non-updateable will be excluded from the SQL UPDATE statement created
2187 \wxheading{Parameters
}
2189 \docparam{pSqlStmt
}{Pointer to storage for the SQL statement retrieved. To be
2190 sure you have adequate space allocated for the SQL statement, allocate
2191 DB
\_MAX\_STATEMENT\_LEN bytes.
}
2192 \docparam{typeOfUpdate
}{The type of update statement being performed. Can be one
2193 of two values: DB
\_UPD\_KEYFIELDS or DB
\_UPD\_WHERE.
}
2194 \docparam{pWhereClause
}{{\it OPTIONAL
}. If the typeOfUpdate is DB
\_UPD\_WHERE,
2195 then you must also pass in a SQL WHERE clause in this argument. Default is "".
}
2199 This member function allows you to see what the SQL UPDATE statement looks like
2200 that the ODBC class library builds. This can be used for debugging purposes if
2201 you are having problems executing your SQL statement.
2203 WHERE and FROM clauses specified using
\helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2204 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
2208 \membersection{wxDbTable::BuildWhereClause
}\label{wxdbtablebuildwhereclause
}
2210 \func{void
}{BuildWhereClause
}{\param{wxString \&
}{pWhereClause
},
2211 \param{int
}{typeOfWhere
},
\param{const wxString \&
}{qualTableName=""
},
2212 \param{bool
}{useLikeComparison=false
}}
2214 Constructs the portion of a SQL statement which would follow the word 'WHERE'
2215 in a SQL statement to be passed to the datasource. The returned string
2216 does NOT include the word 'WHERE'.
2218 \wxheading{Parameters
}
2220 \docparam{pWhereClause
}{Pointer to storage for the SQL statement retrieved.
2221 To be sure you have adequate space allocated for the SQL statement, allocate
2222 DB
\_MAX\_STATEMENT\_LEN bytes.
}
2223 \docparam{typeOfWhere
}{The type of where clause to generate. Can be one of
2224 two values: DB
\_WHERE\_KEYFIELDS or DB
\_WHERE\_MATCHING.
}
2225 \docparam{qualTableName
}{{\it OPTIONAL
}. Prepended to all base table
2226 column names. For use when a FROM clause has been specified with the
2227 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
},
2228 to clarify which table a column name reference belongs to. Default is "".
}
2229 \docparam{useLikeComparison
}{{\it OPTIONAL
}. Should the constructed WHERE
2230 clause utilize the LIKE comparison operator. If false, then the '='
2231 operator is used. Default is false.
}
2235 This member function allows you to see what the SQL WHERE clause looks like
2236 that the ODBC class library builds. This can be used for debugging purposes
2237 if you are having problems executing your own SQL statements.
2239 If using 'typeOfWhere' set to DB
\_WHERE\_MATCHING, any bound columns currently
2240 containing a NULL value are not included in the WHERE clause's list of
2241 columns to use in the comparison.
2244 \membersection{wxDbTable::CanSelectForUpdate
}\label{wxdbtablecanselectforupdate
}
2246 \func{bool
}{CanSelectForUpdate
}{\void}
2248 Use this function to determine if the datasource supports SELECT ... FOR UPDATE.
2249 When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement,
2250 all records
{\it retrieved
} (not just queried, but actually retrieved using
2251 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}, etc) from the result set are
2256 Not all datasources support the "FOR UPDATE" clause, so you must use this
2257 member function to determine if the datasource currently connected to supports
2258 this behavior or not before trying to select using "FOR UPDATE".
2260 If the wxDbTable instance was created with the parameter wxDB
\_QUERY\_ONLY, then
2261 this function will return false. For all known databases which do not support
2262 the FOR UPDATE clause, this function will return false also.
2264 \membersection{wxDbTable::CanUpdateByROWID
}\label{wxdbtablecanupdatebyrowid
}
2266 \func{bool
}{CanUpdateByROWID
}{\void}
2268 CURRENTLY ONLY POSSIBLE IF USING ORACLE.
2270 --- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV
1 2000 - gt
2272 Every Oracle table has a hidden column named ROWID. This is a pointer to the
2273 physical location of the record in the datasource and allows for very fast
2274 updates and deletes. The key is to retrieve this ROWID during your query so
2275 it is available during an update or delete operation.
2277 Use of the ROWID feature is always handled by the class library except in the
2278 case of
\helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}. Since
2279 you are passing in the SQL SELECT statement,
2280 it is up to you to include the ROWID column in your query. If you do not,
2281 the application will still work, but may not be as optimized. The ROWID is
2282 always the last column in the column list in your SQL SELECT statement.
2283 The ROWID is not a column in the normal sense and should not be considered
2284 part of the column definitions for the wxDbTable object.
2288 The decision to include the ROWID in your SQL SELECT statement must be
2289 deferred until runtime since it depends on whether you are connected
2290 to an Oracle datasource or not.
2295 // Incomplete code sample
2298 if (parts.CanUpdateByROWID())
2300 // Note that the ROWID column must always be the last column selected
2301 sqlStmt = "SELECT PART_NUM, PART_DESC, ROWID" FROM PARTS";
2304 sqlStmt = "SELECT PART_NUM, PART_DESC FROM PARTS";
2308 \membersection{wxDbTable::ClearMemberVar
}\label{wxdbtableclearmembervar
}
2310 \func{void
}{ClearMemberVar
}{\param{UWORD
}{colNumber
},
\param{bool
}{setToNull=false
}}
2312 Same as
\helpref{wxDbTable::ClearMemberVars
}{wxdbtableclearmembervars
} except
2313 that this function clears only the specified column of its values, and
2314 optionally sets the column to be a NULL column.
2316 \docparam{colNumber
}{Column number that is to be cleared. This number (between
0
2317 and (numColumns-
1)) is the index of the column definition created using the
2318 \helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
} function.
}
2319 \docparam{setToNull
}{{\it OPTIONAL
}. Indicates whether the column should be
2320 flagged as being a NULL value stored in the bound memory variable. If true,
2321 then any value stored in the bound member variable is cleared. Default is
2324 \membersection{wxDbTable::ClearMemberVars
}\label{wxdbtableclearmembervars
}
2326 \func{void
}{ClearMemberVars
}{\param{bool
}{setToNull=false
}}
2328 Initializes all bound columns of the wxDbTable instance to zero. In the case
2329 of a string, zero is copied to the first byte of the string.
2331 \docparam{setToNull
}{{\it OPTIONAL
}. Indicates whether all columns should be
2332 flagged as having a NULL value stored in the bound memory variable. If true,
2333 then any value stored in the bound member variable is cleared. Default is
2338 This is useful before calling functions such as
2339 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2340 \helpref{wxDbTable::DeleteMatching
}{wxdbtabledeletematching
} since these
2341 functions build their WHERE clauses from non-zero columns. To call either
2342 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2343 \helpref{wxDbTable::DeleteMatching
}{wxdbtabledeletematching
} use this sequence:
2346 1) ClearMemberVars()
2347 2) Assign columns values you wish to match on
2348 3) Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
2351 \membersection{wxDbTable::CloseCursor
}\label{wxdbtableclosecursor
}
2353 \func{bool
}{CloseCursor
}{\param{HSTMT
}{cursor
}}
2355 Closes the specified cursor associated with the wxDbTable object.
2357 \wxheading{Parameters
}
2359 \docparam{cursor
}{The cursor to be closed.
}
2363 Typically handled internally by the ODBC class library, but may be used by the
2364 programmer if desired.
2366 \normalbox{DO NOT CLOSE THE wxDB
\_DEFAULT\_CURSOR!
}
2368 \membersection{wxDbTable::Count
}\label{wxdbtablecount
}
2370 \func{ULONG
}{Count
}{\param{const wxString \&
}{args="*"
}}
2372 Returns the number of records which would be in the result set using the
2373 current query parameters specified in the WHERE and FROM clauses.
2375 \wxheading{Parameters
}
2377 \docparam{args
}{{\it OPTIONAL
}. This argument allows the use of the
2378 DISTINCT keyword against a column name to cause the returned count to
2379 only indicate the number of rows in the result set that have a unique
2380 value in the specified column. An example is shown below. Default is "*",
2381 meaning a count of the total number of rows matching is returned, regardless
2386 This function can be called before or after an actual query to obtain the
2387 count of records in the result set. Count() uses its own cursor, so result
2388 set cursor positioning is not affected by calls to Count().
2390 WHERE and FROM clauses specified using
2391 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2392 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} ARE used by
2401 FIRST_NAME LAST_NAME
2402 ----------- ----------
2408 // Incomplete code sample
2411 users.SetWhereClause("");
2413 // This Count() will return
4, as there are four users listed above
2414 // that match the query parameters
2415 totalNumberOfUsers = users.Count();
2417 // This Count() will return
3, as there are only
3 unique first names
2418 // in the table above - John, Richard, Michael.
2419 totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
2422 \membersection{wxDbTable::CreateIndex
}\label{wxdbtablecreateindex
}
2424 \func{bool
}{CreateIndex
}{\param{const wxString \&
}{IndexName
},
\param{bool
}{unique
},
2425 \param{UWORD
}{numIndexColumns
},
\param{wxDbIdxDef *
}{pIndexDefs
},
2426 \param{bool
}{attemptDrop=true
}}
2428 This member function allows you to create secondary (non primary) indexes on
2429 your tables. You first create your table, normally specifying a primary
2430 index, and then create any secondary indexes on the table. Indexes in
2431 relational model are not required. You do not need indexes to look up records
2432 in a table or to join two tables together. In the relational model, indexes,
2433 if available, provide a quicker means to look up data in a table. To enjoy
2434 the performance benefits of indexes, the indexes must be defined on the
2435 appropriate columns and your SQL code must be written in such a way as to
2436 take advantage of those indexes.
2438 \wxheading{Parameters
}
2440 \docparam{IndexName
}{Name of the Index. Name must be unique within the table
2441 space of the datasource.
}
2442 \docparam{unique
}{Indicates if this index is unique.
}
2443 \docparam{numIndexColumns
}{Number of columns in the index.
}
2444 \docparam{pIndexDefs
}{A pointer to an array
\helpref{wxDbIdxDef
}{wxdbidxdef
} structures.
}
2445 \docparam{attemptDrop
}{{\it OPTIONAL
}. Indicates if the function should try
2446 to execute a
\helpref{wxDbTable::DropIndex
}{wxdbtabledropindex
} on the index
2447 name provided before trying to create the index name. Default is true.
}
2451 The first parameter, index name, must be unique and should be given a
2452 meaningful name. Common practice is to include the table name as a prefix
2453 in the index name (e.g. For table PARTS, you might want to call your index
2454 PARTS
\_Index1). This will allow you to easily view all
2455 of the indexes defined for a given table grouped together alphabetically.
2457 The second parameter indicates if the index is unique or not. Uniqueness
2458 is enforced at the RDBMS level preventing rows which would have duplicate
2459 indexes from being inserted into the table when violating a unique index's
2462 In the third parameter, specify how many columns are in your index. This
2463 number must match the number of columns defined in the 'pIndexDefs' parameter.
2465 The fourth parameter specifies which columns make up the index using the
2466 \helpref{wxDbIdxDef
}{wxdbidxdef
} structure. For each column in the index, you must specify two
2467 things, the column name and the sort order (ascending / descending). See
2468 the example below to see how to build and pass in the
\helpref{wxDbIdxDef
}{wxdbidxdef
} structure.
2470 The fifth parameter is provided to handle the differences in datasources as
2471 to whether they will automatically overwrite existing indexes with the same
2472 name or not. Some datasources require that the existing index must be dropped
2473 first, so this is the default behavior.
2475 Some datasources (MySQL, and possibly others) require columns which are to be
2476 part of an index to be defined as NOT NULL. When this function is called, if
2477 a column is not defined to be NOT NULL, a call to this function will modify
2478 the column definition to change any columns included in the index to be
2479 NOT NULL. In this situation, if a NULL value already exists in one of the
2480 columns that is being modified, creation of the index will fail.
2482 PostGres is unable to handle index definitions which specify whether the index
2483 is ascending or descending, and defaults to the system default when the index
2486 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
2487 after executing this function.
2492 // Create a secondary index on the PARTS table
2493 wxDbIdxDef IndexDef
[2]; //
2 columns make up the index
2495 wxStrcpy(IndexDef
[0].ColName, "PART_DESC"); // Column
1
2496 IndexDef
[0].Ascending = true;
2498 wxStrcpy(IndexDef
[1].ColName, "SERIAL_NO"); // Column
2
2499 IndexDef
[1].Ascending = false;
2501 // Create a name for the index based on the table's name
2503 indexName.Printf("
%s_Index1",parts->GetTableName());
2504 parts->CreateIndex(indexName, true,
2, IndexDef);
2507 \membersection{wxDbTable::CreateTable
}\label{wxdbtablecreatetable
}
2509 \func{bool
}{CreateTable
}{\param{bool
}{attemptDrop=true
}}
2511 Creates a table based on the definitions previously defined for this
2514 \wxheading{Parameters
}
2516 \docparam{attemptDrop
}{{\it OPTIONAL
}. Indicates whether the driver should
2517 attempt to drop the table before trying to create it. Some datasources will
2518 not allow creation of a table if the table already exists in the table space
2519 being used. Default is true.
}
2523 This function creates the table and primary index (if any) in the table space
2524 associated with the connected datasource. The owner of these objects will
2525 be the user id that was given when
\helpref{wxDb::Open
}{wxdbopen
} was called.
2526 The objects will be created in the default schema/table space for that user.
2528 In your derived wxDbTable object constructor, the columns and primary index
2529 of the table are described through the
\helpref{wxDbColDef
}{wxdbcoldef
} structure.
2530 \helpref{wxDbTable::CreateTable
}{wxdbtablecreatetable
} uses this information
2531 to create the table and to add the primary index. See
2532 \helpref{wxDbTable
}{wxdbtable
} ctor and wxDbColDef description for additional
2533 information on describing the columns of the table.
2535 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
2536 after executing this function.
2538 \membersection{wxDbTable::DB
\_STATUS}\label{wxdbtabledbstatus
}
2540 \func{bool
}{DB
\_STATUS}{\void}
2542 Accessor function that returns the wxDb private member variable DB
\_STATUS for
2543 the database connection used by this instance of wxDbTable.
2545 \membersection{wxDbTable::Delete
}\label{wxdbtabledelete
}
2547 \func{bool
}{Delete
}{\void}
2549 Deletes the row from the table indicated by the current cursor.
2553 Use
\helpref{wxDbTable::GetFirst
}{wxdbtablegetfirst
},
2554 \helpref{wxDbTable::GetLast
}{wxdbtablegetlast
},
2555 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
} or
2556 \helpref{wxDbTable::GetPrev
}{wxdbtablegetprev
} to position the cursor to
2557 a valid record. Once positioned on a record, call this function to delete
2558 the row from the table.
2560 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
2561 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
2562 this function to commit or rollback the deletion.
2564 NOTE: Most datasources have a limited size "rollback" segment. This means
2565 that it is only possible to insert/update/delete a finite number of rows
2566 without performing a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
2567 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
}. Size of the rollback
2568 segment varies from database to database, and is user configurable in
2569 most databases. Therefore it is usually best to try to perform a commit
2570 or rollback at relatively small intervals when processing a larger number
2571 of actions that insert/update/delete rows in a table.
2573 \membersection{wxDbTable::DeleteCursor
}\label{wxdbtabledeletecursor
}
2575 \func{bool
}{DeleteCursor
}{\param{HSTMT *
}{hstmtDel
}}
2577 Allows a program to delete a cursor.
2579 \wxheading{Parameters
}
2581 \docparam{hstmtDel
}{Handle of the cursor to delete.
}
2585 For default cursors associated with the instance of wxDbTable, it is not
2586 necessary to specifically delete the cursors. This is automatically done
2587 in the wxDbTable destructor.
2589 NOTE: If the cursor could not be deleted for some reason, an error is logged
2590 indicating the reason. Even if the cursor could not be deleted, the HSTMT
2591 that is passed in is deleted, and the pointer is set to NULL.
2593 \normalbox{DO NOT DELETE THE wxDB
\_DEFAULT\_CURSOR!
}
2595 \membersection{wxDbTable::DeleteMatching
}\label{wxdbtabledeletematching
}
2597 \func{bool
}{DeleteMatching
}{\void}
2599 This member function allows you to delete records from your wxDbTable object
2600 by specifying the data in the columns to match on.
2604 To delete all users with a first name of "JOHN", do the following:
2606 \begin{enumerate
}\itemsep=
0pt
2607 \item Clear all "columns" using wxDbTable::ClearMemberVars().
2608 \item Set the FIRST
\_NAME column equal to "JOHN".
2609 \item Call wxDbTable::DeleteMatching().
2612 The WHERE clause is built by the ODBC class library based on all non-NULL
2613 columns. This allows deletion of records by matching on any column(s) in
2614 your wxDbTable instance, without having to write the SQL WHERE clause.
2616 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
2617 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
2618 this function to commit or rollback the deletion.
2620 NOTE: Row(s) should be locked before deleting them to make sure they are
2621 not already in use. This can be achieved by calling
2622 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
},
2623 and then retrieving the records, locking each as you go (assuming FOR UPDATE
2624 is allowed on the datasource). After the row(s) have been successfully locked,
2627 NOTE: Most datasources have a limited "rollback" segment. This means
2628 that it is only possible to insert/update/delete a finite number of rows
2629 without performing a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
2630 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
}. Size of the rollback
2631 segment varies from database to database, and is user configurable in
2632 most databases. Therefore it is usually best to try to perform a commit
2633 or rollback at relatively small intervals when processing a larger number
2634 of actions that insert/update/delete rows in a table.
2639 // Incomplete code sample to delete all users with a first name
2641 users.ClearMemberVars();
2642 wxStrcpy(users.FirstName,"JOHN");
2643 users.DeleteMatching();
2647 \membersection{wxDbTable::DeleteWhere
}\label{wxdbtabledeletewhere
}
2649 \func{bool
}{DeleteWhere
}{\param{const wxString \&
}{pWhereClause
}}
2651 Deletes all rows from the table which match the criteria specified in the
2652 WHERE clause that is passed in.
2654 \wxheading{Parameters
}
2656 \docparam{pWhereClause
}{SQL WHERE clause. This WHERE clause determines which
2657 records will be deleted from the table interfaced through the wxDbTable
2658 instance. The WHERE clause passed in must be compliant with the SQL
92
2659 grammar. Do not include the keyword 'WHERE'
2664 This is the most powerful form of the wxDbTable delete functions. This
2665 function gives access to the full power of SQL. This function can be used
2666 to delete records by passing a valid SQL WHERE clause. Sophisticated
2667 deletions can be performed based on multiple criteria using the full
2668 functionality of the SQL language.
2670 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} must be called after use of
2671 this function to commit the deletions.
2673 Note: This function is limited to deleting records from the table associated
2674 with this wxDbTable object only. Deletions on joined tables is not possible.
2676 NOTE: Most datasources have a limited size "rollback" segment. This means
2677 that it is only possible to insert/update/delete a finite number of rows
2678 without performing a
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
2679 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
}. Size of the rollback
2680 segment varies from database to database, and is user configurable in
2681 most databases. Therefore it is usually best to try to perform a commit
2682 or rollback at relatively small intervals when processing a larger number
2683 of actions that insert/update/delete rows in a table.
2685 WHERE and FROM clauses specified using
\helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
2686 and
\helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} are ignored by
2692 // Delete parts
1 thru
10 from containers 'X', 'Y' and 'Z' that
2693 // are magenta in
color
2694 parts.DeleteWhere("(PART_NUMBER BETWEEN
1 AND
10) AND \
2695 CONTAINER IN ('X', 'Y', 'Z') AND \
2696 UPPER(COLOR) = 'MAGENTA'");
2700 \membersection{wxDbTable::DropIndex
}\label{wxdbtabledropindex
}
2702 \func{bool
}{DropIndex
}{\param{const wxString \&
}{IndexName
}}
2704 Allows an index on the associated table to be dropped (deleted) if the user
2705 login has sufficient privileges to do so.
2707 \wxheading{Parameters
}
2709 \docparam{IndexName
}{Name of the index to be dropped.
}
2713 If the index specified in the 'IndexName' parameter does not exist, an error
2714 will be logged, and the function will return a result of false.
2716 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
2717 after executing this function.
2719 \membersection{wxDbTable::DropTable
}\label{wxdbtabledroptable
}
2721 \func{bool
}{DropTable
}{\void}
2723 Deletes the associated table if the user has sufficient privileges to do so.
2727 This function returns true if the table does not exist, but only for
2728 supported databases (see
\helpref{wxDb::Dbms
}{wxdbdbms
}). If a datasource
2729 is not specifically supported, and this function is called, the function
2732 Most datasources/ODBC drivers will delete any indexes associated with the
2733 table automatically, and others may not. Check the documentation for your
2734 database to determine the behavior.
2736 It is not necessary to call
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
}
2737 after executing this function.
2739 \membersection{wxDbTable::From
}\label{wxdbtablefrom
}
2741 \func{const wxString \&
}{From
}{}
2743 \func{void
}{From
}{\param{const wxString \&
}{From
}}
2745 Accessor function for the private class member wxDbTable::from. Can be used
2746 as a synonym for
\helpref{wxDbTable::GetFromClause
}{wxdbtablegetfromclause
}
2747 (the first form of this function) or
2748 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} (the second form
2751 \wxheading{Parameters
}
2753 \docparam{From
}{A comma separated list of table names that are to be outer
2754 joined with the base table's columns so that the joined table's columns
2755 may be returned in the result set or used as a portion of a comparison with
2756 the base table's columns. NOTE that the base tables name must NOT be included
2757 in the FROM clause, as it is automatically included by the wxDbTable class
2758 in constructing query statements.
}
2760 \wxheading{Return value
}
2762 The first form of this function returns the current value of the wxDbTable
2763 member variable ::from.
2765 The second form of the function has no return value, as it will always set
2766 the from clause successfully.
2768 \wxheading{See also
}
2770 \helpref{wxDbTable::GetFromClause
}{wxdbtablegetfromclause
},
2771 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}
2774 \membersection{wxDbTable::GetColDefs
}\label{wxdbtablegetcoldefs
}
2776 \func{wxDbColDef *
}{GetColDefs
}{}
2778 Accessor function that returns a pointer to the array of column definitions
2779 that are bound to the columns that this wxDbTable instance is associated
2782 To determine the number of elements pointed to by the returned
2783 \helpref{wxDbColDef
}{wxdbcoldef
} pointer, use the
2784 \helpref{wxDbTable::GetNumberOfColumns
}{wxdbtablegetnumberofcolumns
} function.
2788 These column definitions must not be manually redefined after they have been
2791 \membersection{wxDbTable::GetCursor
}\label{wxdbtablegetcursor
}
2793 \func{HSTMT
}{GetCursor
}{\void}
2795 Returns the HSTMT value of the current cursor for this wxDbTable object.
2799 This function is typically used just before changing to use a different cursor
2800 so that after the program is finished using the other cursor, the current
2801 cursor can be set back to being the cursor in use.
2803 \wxheading{See also
}
2805 \helpref{wxDbTable::SetCursor
}{wxdbtablesetcursor
},
\helpref{wxDbTable::GetNewCursor
}{wxdbtablegetnewcursor
}
2807 \membersection{wxDbTable::GetDb
}\label{wxdbtablegetdb
}
2809 \func{wxDb *
}{GetDb
}{}
2811 Accessor function for the private member variable pDb which is a pointer to
2812 the datasource connection that this wxDbTable instance uses.
2814 \membersection{wxDbTable::GetFirst
}\label{wxdbtablegetfirst
}
2816 \func{bool
}{GetFirst
}{\void}
2818 Retrieves the FIRST row in the record set as defined by the current query.
2819 Before retrieving records, a query must be performed using
2820 \helpref{wxDbTable::Query
}{wxdbtablequery
},
2821 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2822 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2823 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2827 This function can only be used if the datasource connection used by the
2828 wxDbTable instance was created with FwdOnlyCursors set to false. If the
2829 connection does not allow backward scrolling cursors, this function will
2830 return false, and the data contained in the bound columns will be undefined.
2832 \wxheading{See also
}
2834 \helpref{wxDb::IsFwdOnlyCursors
}{wxdbisfwdonlycursors
}
2836 \membersection{wxDbTable::GetFromClause
}\label{wxdbtablegetfromclause
}
2838 \func{const wxString \&
}{GetFromClause
}{}
2840 Accessor function that returns the current FROM setting assigned with the
2841 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}.
2843 \wxheading{See also
}
2845 \helpref{wxDbTable::From
}{wxdbtablefrom
}
2847 \membersection{wxDbTable::GetLast
}\label{wxdbtablegetlast
}
2849 \func{bool
}{GetLast
}{\void}
2851 Retrieves the LAST row in the record set as defined by the current query.
2852 Before retrieving records, a query must be performed using
2853 \helpref{wxDbTable::Query
}{wxdbtablequery
},
2854 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2855 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2856 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2860 This function can only be used if the datasource connection used by the
2861 wxDbTable instance was created with FwdOnlyCursors set to false. If the
2862 connection does not allow backward scrolling cursors, this function will
2863 return false, and the data contained in the bound columns will be undefined.
2865 \wxheading{See also
}
2867 \helpref{wxDb::IsFwdOnlyCursors
}{wxdbisfwdonlycursors
}
2869 \membersection{wxDbTable::GetNewCursor
}\label{wxdbtablegetnewcursor
}
2871 \func{HSTMT *
}{GetNewCursor
}{\param{bool
}{setCursor=false
},
2872 \param{bool
}{bindColumns=true
}}
2874 This function will create a new cursor that can be used to access the table
2875 being referenced by this wxDbTable instance, or to execute direct SQL commands
2876 on without affecting the cursors that are already defined and possibly
2879 \wxheading{Parameters
}
2881 \docparam{setCursor
}{{\it OPTIONAL
}. Should this new cursor be set to be the
2882 current cursor after successfully creating the new cursor. Default is false.
}
2883 \docparam{bindColumns
}{{\it OPTIONAL
}. Should this new cursor be bound to all
2884 the memory variables that the default cursor is bound to. Default is true.
}
2888 This new cursor must be closed using
2889 \helpref{wxDbTable::DeleteCursor
}{wxdbtabledeletecursor
}
2890 by the calling program before the wxDbTable instance is deleted, or both
2891 memory and resource leaks will occur.
2893 \membersection{wxDbTable::GetNext
}\label{wxdbtablegetnext
}
2895 \func{bool
}{GetNext
}{\void}
2897 Retrieves the NEXT row in the record set after the current cursor position
2898 as defined by the current query. Before retrieving records, a query must be
2899 performed using
\helpref{wxDbTable::Query
}{wxdbtablequery
},
2900 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2901 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2902 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2904 \wxheading{Return value
}
2906 This function returns false when the current cursor has reached the end of
2907 the result set. When false is returned, data in the bound columns is
2912 This function works with both forward and backward scrolling cursors.
2914 \wxheading{See also
}
2915 \helpref{wxDbTable::++
}{wxdbtableplusplus
}
2917 \membersection{wxDbTable::GetNumberOfColumns
}\label{wxdbtablegetnumberofcolumns
}
2919 \func{UWORD
}{GetNumberOfColumns
}{}
2921 Accessor function that returns the number of columns that are statically
2922 bound for access by the wxDbTable instance.
2924 \membersection{wxDbTable::GetOrderByClause
}\label{wxdbtablegetorderbyclause
}
2926 \func{const wxString \&
}{GetOrderByClause
}{}
2928 Accessor function that returns the current ORDER BY setting assigned with
2929 the
\helpref{wxDbTable::SetOrderByClause
}{wxdbtablesetorderbyclause
}.
2931 \wxheading{See also
}
2933 \helpref{wxDbTable::OrderBy
}{wxdbtableorderby
}
2935 \membersection{wxDbTable::GetPrev
}\label{wxdbtablegetprev
}
2937 \func{bool
}{GetPrev
}{\void}
2939 Retrieves the PREVIOUS row in the record set before the current cursor
2940 position as defined by the current query. Before retrieving records, a
2941 query must be performed using
\helpref{wxDbTable::Query
}{wxdbtablequery
},
2942 \helpref{wxDbTable::QueryOnKeyFields
}{wxdbtablequeryonkeyfields
},
2943 \helpref{wxDbTable::QueryMatching
}{wxdbtablequerymatching
} or
2944 \helpref{wxDbTable::QueryBySqlStmt
}{wxdbtablequerybysqlstmt
}.
2946 \wxheading{Return value
}
2948 This function returns false when the current cursor has reached the beginning
2949 of the result set and there are now other rows prior to the cursors current
2950 position. When false is returned, data in the bound columns is undefined.
2954 This function can only be used if the datasource connection used by the
2955 wxDbTable instance was created with FwdOnlyCursors set to false. If the
2956 connection does not allow backward scrolling cursors, this function will
2957 return false, and the data contained in the bound columns will be undefined.
2959 \wxheading{See also
}
2961 \helpref{wxDb::IsFwdOnlyCursors
}{wxdbisfwdonlycursors
},
2962 \helpref{wxDbTable::--
}{wxdbtableminusminus
}
2964 \membersection{wxDbTable::GetQueryTableName
}\label{wxdbtablegetquerytablename
}
2966 \func{const wxString \&
}{GetQueryTableName
}{}
2968 Accessor function that returns the name of the table/view that was indicated
2969 as being the table/view to query against when this wxDbTable instance was
2972 \wxheading{See also
}
2974 \helpref{wxDbTable constructor
}{wxdbtableconstr
}
2976 \membersection{wxDbTable::GetRowNum
}\label{wxdbtablegetrownum
}
2978 \func{UWORD
}{GetRowNum
}{\void}
2980 Returns the ODBC row number for performing positioned updates and deletes.
2984 This function is not being used within the ODBC class library and may be a
2985 candidate for removal if no use is found for it.
2987 Row number with some datasources/ODBC drivers is the position in the result set,
2988 while in others it may be a physical position in the database. Check your
2989 database documentation to find out which behavior is supported.
2991 \membersection{wxDbTable::GetTableName
}\label{wxdbtablegettablename
}
2993 \func{const wxString \&
}{GetTableName
}{}
2995 Accessor function that returns the name of the table that was indicated
2996 as being the table that this wxDbTable instance was associated with.
2998 \membersection{wxDbTable::GetTablePath
}\label{wxdbtablegettablepath
}
3000 \func{const wxString \&
}{GetTablePath
}{}
3002 Accessor function that returns the path to the data table that was indicated
3003 during creation of this wxDbTable instance.
3007 Currently only applicable to dBase and MS-Access datasources.
3009 \membersection{wxDbTable::GetWhereClause
}\label{wxdbtablegetwhereclause
}
3011 \func{const wxString \&
}{GetWhereClause
}{}
3013 Accessor function that returns the current WHERE setting assigned with the
3014 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
3016 \wxheading{See also
}
3018 \helpref{wxDbTable::Where
}{wxdbtablewhere
}
3020 \membersection{wxDbTable::Insert
}\label{wxdbtableinsert
}
3022 \func{int
}{Insert
}{\void}
3024 Inserts a new record into the table being referenced by this wxDbTable
3025 instance. The values in the member variables of the wxDbTable instance are
3026 inserted into the columns of the new row in the database.
3028 \wxheading{Return value
}
3031 DB_SUCCESS Record inserted successfully (value =
1)
3033 DB_FAILURE Insert failed (value =
0)
3035 DB_ERR_INTEGRITY_CONSTRAINT_VIOL
3036 The insert failed due to an integrity
3037 constraint violation (duplicate non-unique
3038 index entry) is attempted.
3043 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
3044 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
3045 this function to commit or rollback the insertion.
3050 // Incomplete code snippet
3051 wxStrcpy(parts->PartName, "
10");
3052 wxStrcpy(parts->PartDesc, "Part
#10");
3054 RETCODE retcode = parts->Insert();
3058 parts->GetDb()->CommitTrans();
3060 case DB_ERR_INTEGRITY_CONSTRAINT_VIOL:
3061 // Current data would result in a duplicate key
3062 // on one or more indexes that do not allow duplicates
3063 parts->GetDb()->RollbackTrans();
3066 // Insert failed for some unexpected reason
3067 parts->GetDb()->RollbackTrans();
3072 \membersection{wxDbTable::IsColNull
}\label{wxdbtableiscolnull
}
3074 \func{bool
}{IsColNull
}{\param{UWORD
}{colNumber
}} const
3076 Used primarily in the ODBC class library to determine if a column value is
3077 set to "NULL". Works for all data types supported by the ODBC class library.
3079 \wxheading{Parameters
}
3081 \docparam{colNumber
}{The column number of the bound column as defined by the
3082 \helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
3083 calls which defined the columns accessible to this wxDbTable instance.
}
3087 NULL column support is currently not fully implemented as of wxWidgets
2.4.
3089 \membersection{wxDbTable::IsCursorClosedOnCommit
}\label{wxdbtableiscursorclosedoncommit
}
3091 \func{bool
}{IsCursorClosedOnCommit
}{\void}
3093 Accessor function to return information collected during the opening of the
3094 datasource connection that is used by this wxDbTable instance. The result
3095 returned by this function indicates whether an implicit closing of the cursor is
3096 done after a commit on the database connection.
3098 \wxheading{Return value
}
3100 Returns true if the cursor associated with this wxDbTable object is closed
3101 after a commit or rollback operation. Returns false otherwise.
3105 If more than one wxDbTable instance used the same database connection, all cursors
3106 which use the database connection are closed on the commit if this function
3109 \membersection{wxDbTable::IsQueryOnly
}\label{wxdbtableisqueryonly
}
3111 \func{bool
}{IsQueryOnly
}{}
3113 Accessor function that returns a value indicating if this wxDbTable instance
3114 was created to allow only queries to be performed on the bound columns. If
3115 this function returns true, then no actions may be performed using this
3116 wxDbTable instance that would modify (insert/delete/update) the table's data.
3118 \membersection{wxDbTable::Open
}\label{wxdbtableopen
}
3120 \func{bool
}{Open
}{\param{bool
}{checkPrivileges=false
},
\param{bool
}{checkTableExists=true
}}
3122 Every wxDbTable instance must be opened before it can be used. This function
3123 checks for the existence of the requested table, binds columns, creates required
3124 cursors, (insert/select and update if connection is not wxDB
\_QUERY\_ONLY) and
3125 constructs the insert statement that is to be used for inserting data as a new
3126 row in the datasource.
3128 NOTE: To retrieve data into an opened table, the of the table must be bound
3129 to the variables in the program via call(s) to
3130 \helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
} before calling Open().
3132 See the
\helpref{database classes overview
}{odbcoverview
} for
3133 an introduction to using the ODBC classes.
3135 \wxheading{Parameters
}
3137 \docparam{checkPrivileges
}{Indicates whether the Open() function should check
3138 whether the current connected user has at least SELECT privileges to access the
3139 table to which they are trying to open. Default is false.
}
3141 \docparam{checkTableExists
}{Indicates whether the Open() function should check
3142 whether the table exists in the database or not before opening it. Default is true.
}
3146 If the function returns a false value due to the table not existing, a log
3147 entry is recorded for the datasource connection indicating the problem
3148 that was detected when checking for table existence. Note that it is usually
3149 best for the calling routine to check for the existence of the table and for
3150 sufficient user privileges to access the table in the mode (wxDB
\_QUERY\_ONLY or
3151 !wxDB
\_QUERY\_ONLY) before trying to open the table for the best possible
3152 explanation as to why a table cannot be opened.
3154 Checking the user's privileges on a table can be quite time consuming during
3155 the open phase. With most applications, the programmer already knows that the
3156 user has sufficient privileges to access the table, so this check is normally
3159 For best performance, open the table, and then use the
3160 \helpref{wxDb::TablePrivileges
}{wxdbtableprivileges
} function
3161 to check the users privileges. Passing a schema to the TablePrivileges()
3162 function can significantly speed up the privileges checks.
3164 \wxheading{See also
}
3166 \helpref{wxDb::TableExists
}{wxdbtableexists
},
3167 \helpref{wxDb::TablePrivileges
}{wxdbtableprivileges
}
3168 \helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
}
3170 \membersection{wxDbTable::OrderBy
}\label{wxdbtableorderby
}
3172 \func{const wxString \&
}{OrderBy
}{}
3174 \func{void
}{OrderBy
}{\param{const wxString \&
}{OrderBy
}}
3176 Accessor function for the private class member wxDbTable::orderBy. Can be
3177 used as a synonym for
3178 \helpref{wxDbTable::GetOrderByClause
}{wxdbtablegetorderbyclause
}
3179 (the first form of this function) or
3180 \helpref{wxDbTable::SetOrderByClause
}{wxdbtablesetorderbyclause
}
3181 (the second form of this function).
3183 \wxheading{Parameters
}
3185 \docparam{OrderBy
}{A comma separated list of column names that indicate the
3186 alphabetized/numeric sorting sequence that the result set is to be returned
3187 in. If a FROM clause has also been specified, each column name specified in
3188 the ORDER BY clause should be prefaced with the table name to which the column
3189 belongs using DOT notation (TABLE
\_NAME.COLUMN
\_NAME).
}
3191 \wxheading{Return value
}
3193 The first form of this function returns the current value of the wxDbTable
3194 member variable ::orderBy.
3196 The second form of the function has no return value.
3198 \wxheading{See also
}
3200 \helpref{wxDbTable::GetOrderByClause
}{wxdbtablegetorderbyclause
},
3201 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}
3203 \membersection{wxDbTable::Query
}\label{wxdbtablequery
}
3205 \func{virtual bool
}{Query
}{\param{bool
}{forUpdate=false
},
\param{bool
}{distinct=false
}}
3207 \wxheading{Parameters
}
3209 \docparam{forUpdate
}{{\it OPTIONAL
}. Gives you the option of locking records
3210 as they are retrieved. If the RDBMS is not capable of the FOR UPDATE clause,
3211 this argument is ignored. See
3212 \helpref{wxDbTable::CanSelectForUpdate
}{wxdbtablecanselectforupdate
} for
3213 additional information regarding this argument. Default is false.
}
3214 \docparam{distinct
}{{\it OPTIONAL
}. Allows selection of only distinct values
3215 from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
3216 applies to all columns returned in the result set, not individual columns.
3221 This function queries records from the datasource based on the three
3222 wxDbTable members: "where", "orderBy", and "from". Use
3223 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
} to filter on
3224 records to be retrieved (e.g. All users with a first name of "JOHN").
3225 Use
\helpref{wxDbTable::SetOrderByClause
}{wxdbtablesetorderbyclause
} to
3226 change the sequence in which records are returned in the result set from
3227 the datasource (e.g. Ordered by LAST
\_NAME). Use
3228 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
} to allow outer
3229 joining of the base table (the one being associated with this instance of
3230 wxDbTable) with other tables which share a related field.
3232 After each of these clauses are set/cleared, call wxDbTable::Query() to
3233 fetch the result set from the datasource.
3235 This scheme has an advantage if you have to requery your record set
3236 frequently in that you only have to set your WHERE, ORDER BY, and FROM
3237 clauses once. Then to refresh the record set, simply call wxDbTable::Query()
3238 as frequently as needed.
3240 Note that repeated calls to wxDbTable::Query() may tax the database
3241 server and make your application sluggish if done too frequently or
3244 The base table name is automatically prepended to the base column names in
3245 the event that the FROM clause has been set (is non-null) using
3246 \helpref{wxDbTable::SetFromClause
}{wxdbtablesetfromclause
}.
3248 The cursor for the result set is positioned
{\it before
} the first record in
3249 the result set after the query. To retrieve the first record, call either
3250 \helpref{wxDbTable::GetFirst
}{wxdbtablegetfirst
} (only if backward scrolling
3251 cursors are available) or
3252 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}. Typically, no data from the
3253 result set is returned to the client driver until a request such as
3254 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
} is performed, so network
3255 traffic and database load are not overwhelmed transmitting data until the
3256 data is actually requested by the client. This behavior is solely dependent
3257 on the ODBC driver though, so refer to the ODBC driver's reference material
3258 for information on its behaviors.
3260 Values in the bound columns' memory variables are undefined after executing a
3261 call to this function and remain that way until a row in the result set is
3262 requested to be returned.
3264 The wxDbTable::Query() function is defined as "virtual" so that it may be
3265 overridden for application specific purposes.
3267 \normalbox{Be sure to set the wxDbTable's "where", "orderBy", and "from"
3268 member variables to "" if they are not to be used in the query. Otherwise,
3269 the results returned may have unexpected results (or no results) due to
3270 improper or incorrect query parameters constructed from the uninitialized
3276 // Incomplete code sample
3277 parts->SetWhereClause("DESCRIPTION = 'FOOD'");
3278 parts->SetOrderByClause("EXPIRATION_DATE");
3279 parts->SetFromClause("");
3280 // Query the records based on the where, orderBy and from clauses
3283 // Display all records queried
3284 while(parts->GetNext())
3285 dispPart(parts); // user defined function
3288 \membersection{wxDbTable::QueryBySqlStmt
}\label{wxdbtablequerybysqlstmt
}
3290 \func{bool
}{QueryBySqlStmt
}{\param{const wxString \&
}{pSqlStmt
}}
3292 Performs a query against the datasource by accepting and passing verbatim the
3293 SQL SELECT statement passed to the function.
3295 \wxheading{Parameters
}
3297 \docparam{pSqlStmt
}{Pointer to the SQL SELECT statement to be executed.
}
3301 This is the most powerful form of the query functions available. This member
3302 function allows a programmer to write their own custom SQL SELECT statement
3303 for requesting data from the datasource. This gives the programmer access
3304 to the full power of SQL for performing operations such as scalar functions,
3305 aggregate functions, table joins, and sub-queries, as well as datasource
3306 specific function calls.
3308 The requirements of the SELECT statement are the following:
3311 \item Must return the correct number of columns. In the derived
3312 wxDbTable constructor, it is specified how many columns are in
3313 the wxDbTable object. The SELECT statement must return exactly
3315 \item The columns must be returned in the same sequence as specified
3316 when defining the bounds columns
\helpref{wxDbTable::SetColDefs
}{wxdbtablesetcoldefs
},
3317 and the columns returned must be of the proper data type. For
3318 example, if column
3 is defined in the wxDbTable bound column
3319 definitions to be a float, the SELECT statement must return a
3320 float for column
3 (e.g. PRICE *
1.10 to increase the price by
3322 \item The ROWID can be included in your SELECT statement as the
{\bf last
}
3323 column selected, if the datasource supports it. Use
3324 wxDbTable::CanUpdateByROWID() to determine if the ROWID can be
3325 selected from the datasource. If it can, much better
3326 performance can be achieved on updates and deletes by including
3327 the ROWID in the SELECT statement.
3330 Even though data can be selected from multiple tables (joins) in your select
3331 statement, only the base table associated with this wxDbTable object
3332 is automatically updated through the ODBC class library. Data from multiple
3333 tables can be selected for display purposes however. Include columns in
3334 the wxDbTable object and mark them as non-updateable (See
3335 \helpref{wxDbColDef
}{wxdbcoldef
} for details). This way columns can be
3336 selected and displayed from other tables, but only the base table will be
3337 updated automatically when performed through the
3338 \helpref{wxDbTable::Update
}{wxdbtableupdate
} function after using this type of
3339 query. To update tables other than the base table, use the
3340 \helpref{wxDbTable::Update
}{wxdbtableupdate
} function passing a SQL statement.
3342 After this function has been called, the cursor is positioned before the
3343 first record in the record set. To retrieve the first record, call
3344 either
\helpref{wxDbTable::GetFirst
}{wxdbtablegetfirst
} or
3345 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}.
3350 // Incomplete code samples
3352 sqlStmt = "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
3353 AND CONTAINER =
12";
3354 // Query the records using the SQL SELECT statement above
3355 parts->QueryBySqlStmt(sqlStmt);
3356 // Display all records queried
3357 while(parts->GetNext())
3360 Example SQL statements
3361 ----------------------
3363 // Table Join returning
3 columns
3364 SELECT PART_NUM, part_desc, sd_name
3365 from parts, storage_devices
3366 where parts.storage_device_id =
3367 storage_devices.storage_device_id
3369 // Aggregate function returning total number of
3370 // parts in container
99
3371 SELECT count
(*) from PARTS where container = 99
3373 // Order by clause; ROWID, scalar function
3374 SELECT PART_NUM, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
3376 where warehouse = 10
3377 order by PART_NUM desc // descending order
3381 where container in (select container
3382 from storage_devices
3383 where device_id = 12)
3386 \membersection{wxDbTable::QueryMatching}\label{wxdbtablequerymatching}
3388 \func{virtual bool }{QueryMatching}{\param{bool }{forUpdate=false},
3389 \param{bool }{distinct=false}}
3391 QueryMatching allows querying of records from the table associated with
3392 the wxDbTable object by matching "columns" to values.
3394 For example: To query the datasource for the row with a PART\_NUMBER column
3395 value of "32", clear all column variables of the wxDbTable object, set the
3396 PartNumber variable that is bound to the PART\_NUMBER column in the wxDbTable
3397 object to "32", and then call wxDbTable::QueryMatching().
3399 \wxheading{Parameters}
3401 \docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
3402 as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
3403 the FOR UPDATE clause, this argument is ignored. See
3404 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3405 additional information regarding this argument. Default is false.}
3406 \docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
3407 from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
3408 applies to all columns returned in the result set, not individual columns.
3413 The SQL WHERE clause is built by the ODBC class library based on all
3414 non-zero/non-NULL columns in your wxDbTable object. Matches can be on one,
3415 many or all of the wxDbTable's columns. The base table name is prepended
3416 to the column names in the event that the wxDbTable's FROM clause is non-null.
3418 This function cannot be used to perform queries which will check for
3419 columns that are 0 or NULL, as the automatically constructed WHERE clause
3420 only will contain comparisons on column member variables that are
3423 The primary difference between this function and \helpref{wxDbTable::QueryOnKeyFields}{wxdbtablequeryonkeyfields}
3424 is that this function can query on any column(s) in the wxDbTable object.
3425 Note however that this may not always be very efficient. Searching on
3426 non-indexed columns will always require a full table scan.
3428 The cursor is positioned before the first record in the record set after
3429 the query is performed. To retrieve the first record, the program must call
3430 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3431 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3433 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3434 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3440 // Incomplete code sample
3441 parts->ClearMemberVars(); // Set all columns to zero
3442 wxStrcpy(parts->PartNumber,"32"); // Set columns to query on
3443 parts->OnHold = true;
3444 parts->QueryMatching(); // Query
3445 // Display all records queried
3446 while(parts->GetNext())
3447 dispPart(parts); // Some application defined function
3450 \membersection{wxDbTable::QueryOnKeyFields}\label{wxdbtablequeryonkeyfields}
3452 \func{bool }{QueryOnKeyFields}{\param{bool }{forUpdate=false},
3453 \param{bool }{distinct=false}}
3455 QueryOnKeyFields provides an easy mechanism to query records in the table
3456 associated with the wxDbTable object by the primary index column(s). Simply
3457 assign the primary index column(s) values and then call this member function
3458 to retrieve the record.
3460 Note that since primary indexes are always unique, this function implicitly
3461 always returns a single record from the database. The base table name is
3462 prepended to the column names in the event that the wxDbTable's FROM clause
3465 \wxheading{Parameters}
3467 \docparam{forUpdate}{{\it OPTIONAL}. Gives you the option of locking records
3468 as they are queried (SELECT ... FOR UPDATE). If the RDBMS is not capable of
3469 the FOR UPDATE clause, this argument is ignored. See
3470 \helpref{wxDbTable::CanSelectForUpdate}{wxdbtablecanselectforupdate} for
3471 additional information regarding this argument. Default is false.}
3472 \docparam{distinct}{{\it OPTIONAL}. Allows selection of only distinct values
3473 from the query (SELECT DISTINCT ... FROM ...). The notion of DISTINCT
3474 applies to all columns returned in the result set, not individual columns.
3479 The cursor is positioned before the first record in the record set after
3480 the query is performed. To retrieve the first record, the program must call
3481 either \helpref{wxDbTable::GetFirst}{wxdbtablegetfirst} or
3482 \helpref{wxDbTable::GetNext}{wxdbtablegetnext}.
3484 WHERE and FROM clauses specified using \helpref{wxDbTable::SetWhereClause}{wxdbtablesetwhereclause}
3485 and \helpref{wxDbTable::SetFromClause}{wxdbtablesetfromclause} are ignored by
3491 // Incomplete code sample
3492 wxStrcpy(parts->PartNumber, "32");
3493 parts->QueryOnKeyFields();
3494 // Display all records queried
3495 while(parts->GetNext())
3496 dispPart(parts); // Some application defined function
3499 \membersection{wxDbTable::Refresh}\label{wxdbtablerefresh}
3501 \func{bool}{Refresh}{\void}
3503 This function re-reads the bound columns into the memory variables, setting
3504 them to the current values stored on the disk.
3506 The cursor position and result set are unaffected by calls to this function.
3507 (The one exception is in the case where the record to be refreshed has been
3508 deleted by some other user or transaction since it was originally retrieved
3509 as part of the result set. For most datasources, the default behavior in
3510 this situation is to return the value that was originally queried for the
3511 result set, even though it has been deleted from the database. But this is
3512 datasource dependent, and should be tested before relying on this behavior.)
3516 This routine is only guaranteed to work if the table has a unique primary
3517 index defined for it. Otherwise, more than one record may be fetched and
3518 there is no guarantee that the correct record will be refreshed. The
3519 table's columns are refreshed to reflect the current data in the database.
3521 \membersection{wxDbTable::SetColDefs}\label{wxdbtablesetcoldefs}
3523 \func{bool}{SetColDefs}{\param{UWORD }{index}, \param{const wxString \&}{fieldName},
3524 \param{int }{dataType}, \param{void *}{pData}, \param{SWORD }{cType},
3525 \param{int }{size}, \param{bool }{keyField = false}, \param{bool }{updateable = true},
3526 \param{bool }{insertAllowed = true}, \param{bool }{derivedColumn = false}}
3528 \func{wxDbColDataPtr *}{SetColDefs}{\param{wxDbColInf *}{colInfs}, \param{UWORD }{numCols}}
3530 \wxheading{Parameters}
3532 \docparam{index}{Column number (0 to n-1, where n is the number of columns
3533 specified as being defined for this wxDbTable instance when the
3534 wxDbTable constructor was called.}
3535 \docparam{fieldName}{Column name from the associated data table.}
3536 \docparam{dataType}{Logical data type. Valid logical types include:}
3539 DB_DATA_TYPE_VARCHAR : strings
3540 DB_DATA_TYPE_INTEGER : non-floating point numbers
3541 DB_DATA_TYPE_FLOAT : floating point numbers
3542 DB_DATA_TYPE_DATE : dates
3545 \docparam{pData}{Pointer to the data object that will hold the column's
3546 value when a row of data is returned from the datasource.}
3547 \docparam{cType}{SQL C Type. This defines the data type that the SQL
3548 representation of the data is converted to to be stored in {\it pData}.
3549 Other valid types are available also, but these are the most common ones:}
3552 SQL_C_CHAR // string - deprecated: use SQL_C_WXCHAR
3553 SQL_C_WXCHAR // string - Used transparently in unicode or non-unicode builds
3563 SQL_C_BOOLEAN // defined in db.h
3564 SQL_C_ENUM // defined in db.h
3567 \docparam{size}{Maximum size in bytes of the {\it pData} object.}
3568 \docparam{keyField}{{\it OPTIONAL}. Indicates if this column is part of the
3569 primary index. Default is false.}
3570 \docparam{updateable}{{\it OPTIONAL}. Are updates allowed on this column?
3572 \docparam{insertAllowed}{{\it OPTIONAL}. Inserts allowed on this column?
3574 \docparam{derivedColumn}{{\it OPTIONAL}. Is this a derived column (non-base
3575 table column for query only)? Default is false.}
3577 \docparam{colInfs}{Pointer to an array of wxDbColInf instances which contains
3578 all the information necessary to create {\it numCols} column definitions.}
3579 \docparam{numCols}{Number of elements of wxDbColInf type that are pointed
3580 to by {\it colInfs}, which are to have column definitions created from them.}
3584 If {\it pData} is to hold a string of characters, be sure to include enough
3585 space for the NULL terminator in pData and in the byte count of {\it size}.
3587 Using the first form of this function, if the column definition is not able
3588 to be created, a value of false is returned. If the specified index of the
3589 column exceeds the number of columns defined in the wxDbTable instance, an
3590 assert is thrown and logged (in debug builds) and a false is returned.
3592 A failure to create the column definition in the second form results in a
3593 value of NULL being returned.
3595 Both forms of this function provide a shortcut for defining the columns in
3596 your wxDbTable object. Use this function in any derived wxDbTable
3597 constructor when describing the column/columns in the wxDbTable object.
3599 The second form of this function is primarily used when the
3600 \helpref{wxDb::GetColumns}{wxdbgetcolumns} function was used to query the
3601 datasource for the column definitions, so that the column definitions are
3602 already stored in wxDbColInf form. One example use of using
3603 \helpref{wxDb::GetColumns}{wxdbgetcolumns} then using this function is if
3604 a data table existed in one datasource, and the table's column definitions
3605 were to be copied over to another datasource or table.
3610 // Long way not using this function
3611 wxStrcpy(colDefs[0].ColName, "PART_NUM");
3612 colDefs[0].DbDataType = DB_DATA_TYPE_VARCHAR;
3613 colDefs[0].PtrDataObj = PartNumber;
3614 colDefs[0].SqlCtype = SQL_C_WXCHAR;
3615 colDefs[0].SzDataObj = PART_NUMBER_LEN;
3616 colDefs[0].KeyField = true;
3617 colDefs[0].Updateable = false;
3618 colDefs[0].InsertAllowed= true;
3619 colDefs[0].DerivedCol = false;
3621 // Shortcut using this function
3622 SetColDefs(0, "PART_NUM", DB_DATA_TYPE_VARCHAR, PartNumber,
3623 SQL_C_WXCHAR, PART_NUMBER_LEN, true, false, true, false);
3626 \membersection{wxDbTable::SetCursor}\label{wxdbtablesetcursor}
3628 \func{void}{SetCursor}{\param{HSTMT *}{hstmtActivate = (void **) wxDB
\_DEFAULT\_CURSOR}}
3630 \wxheading{Parameters
}
3632 \docparam{hstmtActivate
}{{\it OPTIONAL
}. Pointer to the cursor that is to
3633 become the current cursor. Passing no cursor handle will reset the cursor
3634 back to the wxDbTable's default (original) cursor that was created when the
3635 wxDbTable instance was first created. Default is wxDB
\_DEFAULT\_CURSOR.
}
3639 When swapping between cursors, the member variables of the wxDbTable object
3640 are automatically refreshed with the column values of the row that the
3641 current cursor is positioned at (if any). If the cursor is not positioned,
3642 then the data in member variables is undefined.
3644 The only way to return back to the cursor that was in use before this
3645 function was called is to programmatically determine the current cursor's HSTMT
3646 {\bf BEFORE
} calling this function using
\helpref{wxDbTable::GetCursor
}{wxdbtablegetcursor
}
3647 and saving a pointer to that cursor.
3649 \wxheading{See also
}
3651 \helpref{wxDbTable::GetNewCursor
}{wxdbtablegetnewcursor
},
3652 \helpref{wxDbTable::GetCursor
}{wxdbtablegetcursor
},
3653 \helpref{wxDbTable::SetCursor
}{wxdbtablesetcursor
}
3655 \membersection{wxDbTable::SetFromClause
}\label{wxdbtablesetfromclause
}
3657 \func{void
}{SetFromClause
}{\param{const wxString \&
}{From
}}
3659 Accessor function for setting the private class member wxDbTable::from
3660 that indicates what other tables should be outer joined with the wxDbTable's
3661 base table for access to the columns in those other tables.
3663 Synonym to this function is one form of
\helpref{wxDbTable::From
}{wxdbtablefrom
}
3665 \wxheading{Parameters
}
3667 \docparam{From
}{A comma separated list of table names that are to be outer
3668 joined with the base table's columns so that the joined table's columns
3669 may be returned in the result set or used as a portion of a comparison with
3670 the base table's columns. NOTE that the base tables name must NOT be included
3671 in the FROM clause, as it is automatically included by the wxDbTable class
3672 in constructing query statements.
}
3676 Used by the
\helpref{wxDbTable::Query
}{wxdbtablequery
} and
3677 \helpref{wxDbTable::Count
}{wxdbtablecount
} member functions to allow outer
3678 joining of records from multiple tables.
3680 Do
{\bf not
} include the keyword "FROM" when setting the FROM clause.
3682 If using the FROM clause when performing a query, be certain to include in
3683 the corresponding WHERE clause a comparison of a column from either the base
3684 table or one of the other joined tables to each other joined table to ensure
3685 the datasource knows on which column values the tables should be joined on.
3691 // Base table is the "LOCATION" table, and it is being
3692 // outer joined to the "PART" table via the the field "PART_NUMBER"
3693 // that can be related between the two tables.
3694 location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
3695 location->SetFromClause("PART");
3699 \wxheading{See also
}
3701 \helpref{wxDbTable::From
}{wxdbtablefrom
},
3702 \helpref{wxDbTable::GetFromClause
}{wxdbtablegetfromclause
}
3704 \membersection{wxDbTable::SetColNull
}\label{wxdbtablesetcolnull
}
3706 \func{bool
}{SetColNull
}{\param{UWORD
}{colNumber
},
\param{bool
}{set=true
}}
3708 \func{bool
}{SetColNull
}{\param{const wxString \&
}{colName
},
3709 \param{bool
}{set=true
}}
3711 Both forms of this function allow a member variable representing a column
3712 in the table associated with this wxDbTable object to be set to NULL.
3714 The first form allows the column to be set by the index into the column
3715 definitions used to create the wxDbTable instance, while the second allows
3716 the actual column name to be specified.
3718 \wxheading{Parameters
}
3720 \docparam{colNumber
}{Index into the column definitions used when first defining
3721 this wxDbTable object.
}
3722 \docparam{colName
}{Actual data table column name that is to be set to NULL.
}
3723 \docparam{set
}{Whether the column is set to NULL or not. Passing true sets
3724 the column to NULL, passing false sets the column to be non-NULL. Default is
3729 No database updates are done by this function. It only operates on the
3730 member variables in memory. Use and insert or update function to store this
3733 \membersection{wxDbTable::SetOrderByClause
}\label{wxdbtablesetorderbyclause
}
3735 \func{void
}{SetOrderByClause
}{\param{const wxString \&
}{OrderBy
}}
3737 Accessor function for setting the private class member wxDbTable::orderBy
3738 which determines sequence/ordering of the rows returned in the result set
3741 A synonym to this function is one form of the function
\helpref{wxDbTable::OrderBy
}{wxdbtableorderby
}
3743 \wxheading{Parameters
}
3745 \docparam{OrderBy
}{A comma separated list of column names that indicate the
3746 alphabetized sorting sequence that the result set is to be returned in. If
3747 a FROM clause has also been specified, each column name specified in the
3748 ORDER BY clause should be prefaced with the table name to which the column
3749 belongs using DOT notation (TABLE
\_NAME.COLUMN
\_NAME).
}
3753 Do
{\bf not
} include the keywords "ORDER BY" when setting the ORDER BY clause.
3759 parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
3763 location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
3767 \wxheading{See also
}
3769 \helpref{wxDbTable::OrderBy
}{wxdbtableorderby
},
3770 \helpref{wxDbTable::GetOrderByClause
}{wxdbtablegetorderbyclause
}
3772 \membersection{wxDbTable::SetQueryTimeout
}\label{wxdbtablesetquerytimeout
}
3774 \func{bool
}{SetQueryTimeout
}{\param{UDWORD
}{nSeconds
}}
3776 Allows a time period to be set as the timeout period for queries.
3778 \wxheading{Parameters
}
3780 \docparam{nSeconds
}{The number of seconds to wait for the query to complete
3785 Neither Oracle or Access support this function as of yet. Other databases
3786 should be evaluated for support before depending on this function working
3789 \membersection{wxDbTable::SetWhereClause
}\label{wxdbtablesetwhereclause
}
3791 \func{void
}{SetWhereClause
}{\param{const wxString \&
}{Where
}}
3793 Accessor function for setting the private class member wxDbTable::where
3794 that determines which rows are returned in the result set by the datasource.
3796 A synonym to this function is one form of the function
\helpref{wxDbTable::Where
}{wxdbtablewhere
}
3798 \wxheading{Parameters
}
3800 \docparam{Where
}{SQL "where" clause. This clause can contain any SQL language
3801 that is legal in standard where clauses. If a FROM clause has also been
3802 specified, each column name specified in the ORDER BY clause should be
3803 prefaced with the table name to which the column belongs using DOT notation
3804 (TABLE
\_NAME.COLUMN
\_NAME).
}
3808 Do
{\bf not
} include the keywords "WHERE" when setting the WHERE clause.
3814 // Simple where clause
3815 parts->SetWhereClause("PART_NUMBER = '
32'");
3817 // Any comparison operators
3818 parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER
%'");
3820 // Multiple comparisons, including a function call
3821 parts->Where("QTY >
0 AND
{fn UCASE(PART_DESCRIP)
} LIKE '
%DRILL%'");
3823 // Using parameters and multiple logical combinations
3824 parts->Where("((QTY >
10) OR (ON_ORDER >
0)) AND ON_HOLD =
0");
3826 // This query uses an outer join (requiring a FROM clause also)
3827 // that joins the PART and LOCATION table on he common field
3829 parts->Where("PART.ON_HOLD =
0 AND \
3830 PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
3831 LOCATION.PART_NUMBER >
0");
3834 \wxheading{See also
}
3836 \helpref{wxDbTable::Where
}{wxdbtablewhere
},
3837 \helpref{wxDbTable::GetWhereClause
}{wxdbtablegetwhereclause
}
3839 \membersection{wxDbTable::Update
}\label{wxdbtableupdate
}
3841 \func{bool
}{Update
}{\void}
3843 \func{bool
}{Update
}{\param{const wxString \&
}{pSqlStmt
}}
3845 The first form of this function will update the row that the current cursor
3846 is currently positioned at with the values in the memory variables that
3847 are bound to the columns. The actual SQL statement to perform the update
3848 is automatically created by the ODBC class, and then executed.
3850 The second form of the function allows full access through SQL statements for
3851 updating records in the database. Write any valid SQL UPDATE statement and
3852 submit it to this function for execution. Sophisticated updates can be
3853 performed using the full power of the SQL dialect. The full SQL statement
3854 must have the exact syntax required by the driver/datasource for performing
3855 the update. This usually is in the form of:
3858 UPDATE tablename SET col1=X, col2=Y, ... where ...
3861 \wxheading{Parameters
}
3863 \docparam{pSqlStmt
}{Pointer to SQL UPDATE statement to be executed.
}
3867 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
3868 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
3869 this function to commit or rollback the update.
3875 sqlStmt = "update PART set QTY =
0 where PART_NUMBER = '
32'";
3878 \membersection{wxDbTable::UpdateWhere
}\label{wxdbtableupdatewhere
}
3880 \func{bool
}{UpdateWhere
}{\param{const wxString \&
}{pWhereClause
}}
3882 Performs updates to the base table of the wxDbTable object, updating only the
3883 rows which match the criteria specified in the
{\it pWhereClause
}.
3885 All columns that are bound to member variables for this wxDbTable instance
3886 that were defined with the "updateable" parameter set to true will be updated
3887 with the information currently held in the memory variable.
3889 \wxheading{Parameters
}
3891 \docparam{pWhereClause
}{Pointer to a valid SQL WHERE clause. Do not
3892 include the keyword 'WHERE'.
}
3896 Care should be used when updating columns that are part of indexes with
3897 this function so as not to violate an unique key constraints.
3899 A
\helpref{wxDb::CommitTrans
}{wxdbcommittrans
} or
3900 \helpref{wxDb::RollbackTrans
}{wxdbrollbacktrans
} must be called after use of
3901 this function to commit or rollback the update(s).
3903 \membersection{wxDbTable::Where
}\label{wxdbtablewhere
}
3905 \func{const wxString \&
}{Where
}{}
3907 \func{void
}{Where
}{\param{const wxString\&
}{Where
}}
3909 Accessor function for the private class member wxDbTable::where. Can be used
3910 as a synonym for
\helpref{wxDbTable::GetWhereClause
}{wxdbtablegetwhereclause
}
3911 (the first form of this function) to return the current where clause or
3912 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
} (the second form
3913 of this function) to set the where clause for this table instance.
3915 \wxheading{Parameters
}
3917 \docparam{Where
}{A valid SQL WHERE clause. Do not include the keyword 'WHERE'.
}
3919 \wxheading{Return value
}
3921 The first form of this function returns the current value of the wxDbTable
3922 member variable ::where.
3924 The second form of the function has no return value, as it will always set
3925 the where clause successfully.
3927 \wxheading{See also
}
3929 \helpref{wxDbTable::GetWhereClause
}{wxdbtablegetwhereclause
},
3930 \helpref{wxDbTable::SetWhereClause
}{wxdbtablesetwhereclause
}
3932 \membersection{wxDbTable::operator $++$
}\label{wxdbtableplusplus
}
3934 \func{bool
}{operator $++$
}{\void}
3936 Synonym for
\helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}
3938 \wxheading{See also
}
3940 \helpref{wxDbTable::GetNext
}{wxdbtablegetnext
}
3942 \membersection{wxDbTable::operator $--$
}\label{wxdbtableminusminus
}
3944 \func{bool
}{operator $--$
}{\void}
3946 Synonym for
\helpref{wxDbTable::GetPrev
}{wxdbtablegetprev
}
3948 \wxheading{See also
}
3950 \helpref{wxDbTable::GetPrev
}{wxdbtablegetprev
}
3952 \section{\class{wxDbTableInf
}}\label{wxdbtableinf
}
3957 tableRemarks
[0] =
0;
3962 Currently only used by
\helpref{wxDb::GetCatalog
}{wxdbgetcatalog
} internally
3963 and
\helpref{wxDbInf
}{wxdbinf
} class, but may be used in future releases for
3964 user functions. Contains information describing the table (Name, type, etc).
3965 A pointer to a wxDbColInf array instance is included so a program can create a
3966 \helpref{wxDbColInf
}{wxdbcolinf
} array instance (using
3967 \helpref{wxDb::GetColumns
}{wxdbgetcolumns
})
3968 to maintain all information about the columns of a table in one memory
3971 Eventually, accessor functions will be added for this class
3973 See the
\helpref{database classes overview
}{odbcoverview
} for
3974 an introduction to using the ODBC classes.
3976 \membersection{wxDbTableInf::Initialize
}\label{wxdbtableinfinitialize
}
3978 Simply initializes all member variables to a cleared state. Called by
3979 the constructor automatically.
3981 \section{\class{wxDbGridColInfo
}}\label{wxdbgridcolinfo
}
3983 This class is used to define columns to be shown, names of the columns,
3984 order and type of data, when using
\helpref{wxdbGridTableBase
}{wxdbgridtablebase
} to display
3985 a Table or query in a
\helpref{wxGrid
}{wxgrid
}
3987 See the database grid example in
\helpref{wxDbGridTableBase
}{wxdbgridtablebase
} for
3988 an introduction to using the wxDbGrid classes.
3990 \wxheading{Include files
}
3994 \latexignore{\rtfignore{\wxheading{Members
}}}
3996 \membersection{wxDbGridColInfo::wxDbGridColInfo
}\label{wxdbgridcolinfoctor
}
3998 \func{}{wxDbGridColInfo
}{\param{int
}{colNumber
},
\param{wxString
}{type
},
3999 \param{wxString
}{title
},
\param{wxDbGridColInfo *
}{next
}}
4001 Default constructor. See the database grid example in
\helpref{wxDbGridTableBase
}{wxdbgridtablebase
} to
4002 see two different ways for adding columns.
4005 \wxheading{Parameters
}
4007 \docparam{colNumber
}{Column number in the
\helpref{wxDbTable
}{wxdbtable
} instance to be used (first column is
0).
}
4008 \docparam{type
}{Column type ,wxString specifying the grid name for the datatype in this column, or
4009 use wxGRID
\_VALUE\_DBAUTO to determine the type automatically from the
\helpref{wxDbColDef
}{wxdbcoldef
} definition
}
4010 \docparam{title
}{The column label to be used in the grid display
}
4011 \docparam{next
}{A pointer to the next wxDbGridColInfo structure if using one-step
4012 construction, NULL terminates the list. Use Null also if using two step construction.
}
4013 See the database grid example in
\helpref{wxDbGridTableBase
}{wxdbgridtablebase
} to
4014 see two different ways for adding columns.
4016 \membersection{wxDbGridColInfo::
\destruct{wxDbGridColInfo
}}\label{wxdbgridcolinfodtor
}
4018 \func{}{\destruct{wxDbGridColInfo
}}{}
4022 \membersection{wxDbGridColInfo::AddColInfo
}\label{wxdbgridcolinfoaddcolinfo
}
4024 \func{void
}{AddColInfo
}{\param{int
}{colNumber
},
4025 \param{wxString
}{type
},
\param{wxString
}{title
}}
4027 Use this member function for adding columns. See the database
4028 grid example in
\helpref{wxDbGridTableBase
}{wxdbgridtablebase
} to
4029 see two different ways for adding columns.
4031 It is important to note that this class is merely a specifier to the
\helpref{wxDbGridTableBase
}{wxdbgridtablebase
}
4032 constructor. Changes made to this datatype after the
\helpref{wxDbGridTableBase
}{wxdbgridtablebase
} is called will
4033 not have any effect.
4035 \wxheading{Parameters
}
4036 \docparam{colNumber
}{Column number in the
\helpref{wxDbTable
}{wxdbtable
} instance to be used (first column is
0).
}
4037 \docparam{type
}{Column type ,wxString specifying the grid name for the datatype in this column, or
4038 use wxGRID
\_VALUE\_DBAUTO to determine the type automatically from the
\helpref{wxDbColDef
}{wxdbcoldef
} definition
}
4039 \docparam{title
}{The column label to be used in the grid display
}
4043 As wxDbTable must be defined with to have columns which match those to by a wxDbGridColInfo
4044 info structure as this is the structure which informs the grid of how you want to display your
4045 \helpref{wxDbTable
}{wxdbtable
}. If no datatype conversion or the referenced column number does not exist the
4046 the behavior is undefined.
4048 See the example at
\helpref{wxDbGridColInfo::wxDbGridColInfo
}{wxdbgridcolinfoctor
}.
4050 \section{\class{wxDbGridTableBase
}}\label{wxdbgridtablebase
}
4052 You can view a database table in a grid using this class.
4054 If you are deriving your own wxDbTable subclass for your table , then you may consider
4055 overriding GetCol() and SetCol() to provide calculated fields. This does work but care should
4056 be taken when using wxDbGridTableBase in this way.
4058 The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable
4059 object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable
4060 when an new on is assigned or wxGridTableBase's destructor is called.
4061 However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true);
4062 is an error. If you need to requery an table object the preferred way is
4063 that the client keeps ownership.
4065 \wxheading{Derived From
}
4067 \helpref{wxGridTableBase
}{wxgridtablebase
}
4069 \wxheading{Include files
}
4077 // First step, let's define wxDbTable
4079 wxDbTable *table = new wxDbTable (db, tblName, numColumns);
4081 wxChar string_name
[255];
4082 table->SetColDef (
0, "column
0", DB_DATA_TYPE_INTEGER, &int_var,
4083 SQL_C_LONG, sizeof(int_var), true);
4084 table->SetColDef (
1, "column
1", DB_DATA_TYPE_VARCHAR, &string_name,
4085 SQL_C_LONG, sizeof(string_name), false);
4087 // now let's define columns in the grid
4089 // first way to do it
4090 wxDbGridColInfo *columns;
4091 columns = new wxDbGridColInfo(
0, wxGRID_VALUE_LONG, "first column",
4092 new wxDbGridColInfo(
1, wxGRID_VALUE_STRING, "second column",
4095 // second way to do it
4096 wxDbGridColInfo *columns;
4097 // first column is special
4098 columns = new wxDbGridColInfo(
0, wxGRID_VALUE_LONG, "first column", NULL);
4100 columns->AddColInfo (
1, wxGRID_VALUE_STRING, "second column");
4102 // second way may be better when columns are not known at compile time
4104 // now, let's open the table and make a Query()
4106 // this step is very important
4107 table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
4108 // in the grid we will see only the rows of the result query
4111 wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, true);
4112 delete columns; // not needed anymore
4113 wxGrid *grid = new wxGrid ( ... );
4114 grid->SetTable(dbgrid, true);
4119 \wxheading{Include files
}
4123 \wxheading{Helper classes and data structures
}
4125 \membersection{wxDbGridTableBase::wxDbGridTableBase
}\label{wxdbgridtablebaseconstr
}
4127 \func{}{wxDbGridTableBase
}{\param{wxDbTable *
}{tab
},
\param{wxDbGridColInfo *
}{ColInfo
},
4128 \param{int
}{count = wxUSE
\_QUERY},
\param{bool
}{takeOwnership = true
}}
4132 \wxheading{Parameters
}
4134 \docparam{tab
}{ The database table you want to display. Must be opened and queried before display the grid.
4135 See the example
\helpref{above
}{wxdbgridtablebase
}.
}
4136 \docparam{ColInfo
}{ Columns titles, and other values. See
\helpref{wxDbGridColInfo
}{wxdbgridcolinfo
}.
}
4137 \docparam{count
}{You can use a query result set (wxUSE
\_QUERY, to use wxDbTable::Count(wxDbTable::Count()
4138 or you can fix the total number of rows (count >=
0) to display, or specify it if you already know the size in avoid calling
}
4140 \docparam{takeOwnership
}{ If true, this class deletes wxDbTable when it stops
4141 referring to it, if false application must
4142 take care of deleting it.
}
4144 \membersection{wxDbGridTableBase::ValidateRow
}\label{wxdbgridtablebasevalidate
}
4146 \func{void
}{ValidateRow
}{\param{int
}{row
}}
4148 It ensures that the row data is fetched from the database, and it the wxDbTable local buffer,
4149 the row number passed should be the grid row.
4151 \wxheading{Parameters
}
4153 \docparam{row
}{ Row where validation must be done.
}
4155 \membersection{wxDbGridTableBase::UpdateRow
}\label{wxdbgridtablebaseupdaterow
}
4157 \func{bool
}{UpdateRow
}{\param{int
}{row
}}
4159 If row has changed it forces that row to be written back to the database, however support
4160 for detecting whether insert/update is required is currently not in wxDbTable, so this
4161 function is currently unsupported.
4163 \wxheading{Parameters
}
4165 \docparam{row
}{ Row you want to update.
}
4167 \membersection{wxDbGridTableBase::AssignDbTable
}\label{wxdbgridtablebaseassigndbtable
}
4169 \func{bool
}{AssignDbTable
}{\param{wxDbTable *
}{tab
},
\param{int
}{count = wxUSE
\_QUERY},
4170 \param{bool
}{takeOwnership = true
}}
4172 Resets the grid for using with a new database table, but using the same columns definition.
4173 This can be useful when re-querying the database and want to see the changes.
4175 \wxheading{Parameters
}
4177 \docparam{tab
}{ Database table you want to assign to the grid.
}
4178 \docparam{count
}{ Number of rows you want to show or wxUSE
\_QUERY for using a query.
}
4179 \docparam{takeOwnership
}{ If false, user must take care of deleting tab after deleting
4180 the wxDbGridTableBase. If true, deletion is made by destructor class.
}