Chapter 3 Class Overview
Kinds of Classes
The DB Interface Module provides the classes you need for data manipulation, error handling, expression formation, database connection, and database portability. As discussed in
Chapter 2, “Design Overview,” SourcePro DB uses a two-module architecture. The DB Interface Module encapsulates database operations and data manipulation, while each database-dependent DB Access Module connects to its related database to normalize its data types.
The DB Interface Module provides both a standard interface, which shields you from SQL, and an alternative interface called Open SQL, which allows you to directly execute SQL statements. For more information on the Open SQL interface, see
“Open SQL Classes”, and
Chapter 15, “Using the Open SQL Classes.” This chapter summarizes the different kinds of classes in the DB Interface Module.
Datatype Classes
SourcePro DB insulates your applications from the variations in data types defined in different databases.
Chapter 7, “The Data Model,” explains in detail how this is done. Applications written with the DB Interface Module work with the primitive C++ data types, plus these additional types:
• RWDBBlob: Binary Large Objects (Blobs).
• RWDBNullIndicator: Used for detecting NULL values when retrieving data from a relational database.
• RWDBValue: Supplied by the DB Interface Module to provide datatype normalization. It is visible to your applications as the datatype of a single cell of an
RWDBRow or an
RWDBMemTable. It is useful for applications that must manipulate data without knowing its type.
The classes
RWCString,
RWDate,
RWTime,
RWDateTime,
RWDecimalPortable,
RWWString, and
RWBasicUString are from the Essential Tools Module of SourcePro Core; all other classes are in the DB Interface Module. Please see their respective sections in the
Essential Tools Module User’s Guide and in this guide. For class descriptions, see the
SourcePro C++ API Reference Guide.
Database Classes
The database classes are the heart of the DB Interface Module. This powerful set of classes is designed to encapsulate common database objects.
• Class
RWDBSystemHandle contains all the hooks used by a DB Access Module to interact with the native database API. Every
RWDBConnection instance has a pointer to an
RWDBSystemHandle. Applications can get direct access to the underlying database API through a connection's system handle.
• Class
RWDBEnvironmentHandle lets you set environment attributes for specific databases. Every
RWDBDatabase instance has a pointer to an
RWDBEnvironmentHandle. To access it, an application calls
RWDBDatabase::environmentHandle(), which returns a pointer to the base class of a family of classes that contain implementation-specific information. Of course, using
RWDBEnvironmentHandle can reduce the portability of applications.
Most database classes are explained in
Chapter 4, “The Database Classes.” Detailed information for each class is in the
SourcePro C++ API Reference Guide.
Data Manipulation Classes
Also essential to the DB Interface Module are the data manipulation classes, which encapsulate common database operations.
Expression Classes
Class
RWDBExpr is a base class for a family of classes in the DB Interface Module that enable you to program SQL expressions in C++. Instances of these expressions are usually created anonymously. For example, the following fragment instantiates several
RWDBExpr objects:
select.where(myTable["col1"] < yourTable["col1"] + 100);
• The DB Interface Module also provides an extensible mechanism for defining SQL expressions for your specific needs. The classes
RWDBExprFormDefinition,
RWDBExprFuncDef{n},
RWDBCritFormDefinition, and
RWDBCritFuncDef{n}support this mechanism. They are discussed in the
SourcePro C++ API Reference Guide.
Bulk Classes
The alternative classes
RWDBBulkReader and
RWDBBulkInserter are designed to help improve application performance.
RWDBBulkReader and
RWDBBulkInserter implement reading (fetching) and writing (inserting) directly to and from arrays supplied by an application.
The template class
RWDBTBuffer<T> works with the bulk read and write classes and can handle most of the supported data types. For possible datatype limitations, see the relevant Access Module User’s Guide.
Examples using
RWDBBulkReader and
RWDBBulkInserter are described in
Chapter 8, “Bulk Reading and Writing.” Detailed explanations of each class are in the
SourcePro C++ API Reference Guide.
Open SQL Classes
The Open SQL interface contains several classes that give you direct control over the execution of SQL statements and the data that is bound to them.
• Class
RWDBOSql encapsulates an SQL statement and its input and output bindings.
• Class
RWDBTBuffer<T>, a template class, encapsulates buffers of data that can be bound to the SQL statement.
Utility and Diagnostics Classes
The utility and diagnostics classes have specific jobs to perform.
• Every DB Access Module contains an instance of a class derived from
RWDBPhraseBook, which is a list of SQL phrases in the dialect of a specific database. Instances of class
RWDBDatabase use the phrasebook from their respective Access Modules to generate SQL statements. Applications can obtain a reference to an
RWDBPhraseBook via the
phraseBook() method of
RWDBDatabase.
• Class
RWDBStatus encapsulates the status of an object or operation, and supports the error model of the DB Interface Module. The error model itself is described in
Chapter 6, “The Error Model.” • Class
RWDBTracer provides a runtime trace of your application's interactions with the database.
The SourcePro C++ API Reference Guide and the DB Access Module guides contain more information on all the classes described here.
Callback Classes
Classes
RWDBDatabaseCallback and
RWDBDatabaseCallbackImp allow you to execute your code at particular callback locations while allocating and deallocating database-specific environment handles. With use of database callbacks, you can customize the database environment handles to your needs.
Classes
RWDBConnCallback and
RWDBConnCallbackImp allow users to execute their code at particular callback locations while allocating, deallocating, connecting and disconnecting database specific connection handles. With use of connection callbacks, you can customize the database connection handles to your needs.
Most callback classes are explained in
Chapter 10, “Callbacks.” Detailed information for each class is in the
SourcePro C++ API Reference Guide.