Contents Up Previous Next

Database classes overview

Classes: wxDatabase, wxRecordSet, wxQueryCol, wxQueryField


Note that more sophisticated ODBC classes are provided by the Remstar database classes: please see the separate HTML and Word documentation.

wxWindows provides a set of classes for accessing a subset of Microsoft's ODBC (Open Database Connectivity) product. Currently, this wrapper is available under MS Windows only, although ODBC may appear on other platforms, and a generic or product-specific SQL emulator for the ODBC classes may be provided in wxWindows at a later date.

ODBC presents a unified API (Application Programmer's Interface) to a wide variety of databases, by interfacing indirectly to each database or file via an ODBC driver. The language for most of the database operations is SQL, so you need to learn a small amount of SQL as well as the wxWindows ODBC wrapper API. Even though the databases may not be SQL-based, the ODBC drivers translate SQL into appropriate operations for the database or file: even text files have rudimentary ODBC support, along with dBASE, Access, Excel and other file formats.

The run-time files for ODBC are bundled with many existing database packages, including MS Office. The required header files, sql.h and sqlext.h, are bundled with several compilers including MS VC++ and Watcom C++. The only other way to obtain these header files is from the ODBC SDK, which is only available with the MS Developer Network CD-ROMs -- at great expense. If you have odbc.dll, you can make the required import library odbc.lib using the tool 'implib'. You need to have odbc.lib in your compiler library path.

The minimum you need to distribute with your application is odbc.dll, which must go in the Windows system directory. For the application to function correctly, ODBC drivers must be installed on the user's machine. If you do not use the database classes, odbc.dll will be loaded but not called (so ODBC does not need to be setup fully if no ODBC calls will be made).

A sample is distributed with wxWindows in samples/odbc. You will need to install the sample dbf file as a data source using the ODBC setup utility, available from the control panel if ODBC has been fully installed.

Procedures for writing an ODBC application
wxDatabase overview
wxQueryCol overview
wxQueryField overview
wxRecordSet overview
ODBC SQL data types
A selection of SQL commands


Procedures for writing an ODBC application

You first need to create a wxDatabase object. If you want to get information from the ODBC manager instead of from a particular database (for example using wxRecordSet::GetDataSources), then you do not need to call wxDatabase::Open. If you do wish to connect to a datasource, then call wxDatabase::Open. You can reuse your wxDatabase object, calling wxDatabase::Close and wxDatabase::Open multiple times.

Then, create a wxRecordSet object for retrieving or sending information. For ODBC manager information retrieval, you can create it as a dynaset (retrieve the information as needed) or a snapshot (get all the data at once). If you are going to call wxRecordSet::ExecuteSQL, you need to create it as a snapshot. Dynaset mode is not yet implemented for user data.

Having called a function such as wxRecordSet::ExecuteSQL or wxRecordSet::GetDataSources, you may have a number of records associated with the recordset, if appropriate to the operation. You can now retrieve information such as the number of records retrieved and the actual data itself. Use wxRecordSet::GetFieldData or wxRecordSet::GetFieldDataPtr to get the data or a pointer to it, passing a column index or name. The data returned will be for the current record. To move around the records, use wxRecordSet::MoveNext, wxRecordSet::MovePrev and associated functions.

You can use the same recordset for multiple operations, or delete the recordset and create a new one.

Note that when you delete a wxDatabase, any associated recordsets also get deleted, so beware of holding onto invalid pointers.


wxDatabase overview

Class: wxDatabase

Every database object represents an ODBC connection. To do anything useful with a database object you need to bind a wxRecordSet object to it. All you can do with wxDatabase is opening/closing connections and getting some info about it (users, passwords, and so on).

See also

Database classes overview


wxQueryCol overview

Class: wxQueryCol

Every data column is represented by an instance of this class. It contains the name and type of a column and a list of wxQueryFields where the real data is stored. The links to user-defined variables are stored here, as well.

See also

Database classes overview


wxQueryField overview

Class: wxQueryField

As every data column is represented by an instance of the class wxQueryCol, every data item of a specific column is represented by an instance of wxQueryField. Each column contains a list of wxQueryFields. If wxRecordSet is of the type wxOPEN_TYPE_DYNASET, there will be only one field for each column, which will be updated every time you call functions like wxRecordSet::Move or wxRecordSet::GoTo. If wxRecordSet is of the type wxOPEN_TYPE_SNAPSHOT, all data returned by an ODBC function will be loaded at once and the number of wxQueryField instances for each column will depend on the number of records.

See also

Database classes overview


wxRecordSet overview

Class: wxRecordSet

Each wxRecordSet represents a database query. You can make multiple queries at a time by using multiple wxRecordSets with a wxDatabase or you can make your queries in sequential order using the same wxRecordSet.

See also

Database classes overview


ODBC SQL data types

These are the data types supported in ODBC SQL. Note that there are other, extended level conformance types, not currently supported in wxWindows.

CHAR(n) A character string of fixed length n.
VARCHAR(n) A varying length character string of maximum length n.
LONG VARCHAR(n) A varying length character string: equivalent to VARCHAR for the purposes of ODBC.
DECIMAL(p, s) An exact numeric of precision p and scale s.
NUMERIC(p, s) Same as DECIMAL.
SMALLINT A 2 byte integer.
INTEGER A 4 byte integer.
REAL A 4 byte floating point number.
FLOAT An 8 byte floating point number.
DOUBLE PRECISION Same as FLOAT.

These data types correspond to the following ODBC identifiers:

SQL_CHAR A character string of fixed length.
SQL_VARCHAR A varying length character string.
SQL_DECIMAL An exact numeric.
SQL_NUMERIC Same as SQL_DECIMAL.
SQL_SMALLINT A 2 byte integer.
SQL_INTEGER A 4 byte integer.
SQL_REAL A 4 byte floating point number.
SQL_FLOAT An 8 byte floating point number.
SQL_DOUBLE Same as SQL_FLOAT.

See also

Database classes overview


A selection of SQL commands

The following is a very brief description of some common SQL commands, with examples.

See also

Database classes overview


Create

Creates a table.

Example:

CREATE TABLE Book
 (BookNumber     INTEGER     PRIMARY KEY
 , CategoryCode  CHAR(2)     DEFAULT 'RO' NOT NULL
 , Title         VARCHAR(100) UNIQUE
 , NumberOfPages SMALLINT
 , RetailPriceAmount NUMERIC(5,2)
 )

Insert

Inserts records into a table.

Example:

INSERT INTO Book
  (BookNumber, CategoryCode, Title)
  VALUES(5, 'HR', 'The Lark Ascending')

Select

The Select operation retrieves rows and columns from a table. The criteria for selection and the columns returned may be specified.

Examples:

SELECT * FROM Book

Selects all rows and columns from table Book.

SELECT Title, RetailPriceAmount FROM Book WHERE RetailPriceAmount > 20.0

Selects columns Title and RetailPriceAmount from table Book, returning only the rows that match the WHERE clause.

SELECT * FROM Book WHERE CatCode = 'LL' OR CatCode = 'RR'

Selects all columns from table Book, returning only the rows that match the WHERE clause.

SELECT * FROM Book WHERE CatCode IS NULL

Selects all columns from table Book, returning only rows where the CatCode column is NULL.

SELECT * FROM Book ORDER BY Title

Selects all columns from table Book, ordering by Title, in ascending order. To specify descending order, add DESC after the ORDER BY Title clause.

SELECT Title FROM Book WHERE RetailPriceAmount >= 20.0 AND RetailPriceAmount <= 35.0

Selects records where RetailPriceAmount conforms to the WHERE expression.


Update

Updates records in a table.

Example:

UPDATE Incident SET X = 123 WHERE ASSET = 'BD34'

This example sets a field in column 'X' to the number 123, for the record where the column ASSET has the value 'BD34'.