DB Interface Module User’s Guide : PART I Introduction : Chapter 3 Class Overview
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:
• RWCString: Character data.
• RWDate: Date values.
• RWDateTime, RWTimeTuple and RWTimeTupleOffset: Date and Time values.
• RWDecimalPortable: Arbitrary precision decimal fraction data.
• RWDBBlob: Binary Large Objects (Blobs).
• RWDBDuration: Time periods.
• RWDBMBString: Multibyte character data.
• 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.
• RWWString: Wide character strings.
• RWBasicUString: UTF-16 Unicode strings.
The classes RWCString, RWDate, 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 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.
• RWDBManager, RWDBDatabase, and RWDBConnection manage database sessions.
• RWDBTable, RWDBColumn, RWDBSchema,and RWDBStoredProc represent the database objects that their names suggest.
• RWDBCheckConstraint, RWDBCheckConstraintList, RWDBUniqueConstraint, RWDBUniqueConstraintList, RWDBIdentityConstraint, RWDBForeignKey, RWDBForeignKeyList, and RWDBPrimaryKey support the SQL constraints on data.
• 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 API Reference Guide.
Data Manipulation Classes
Also essential to the DB Interface Module are the data manipulation classes, which encapsulate common database operations.
• RWDBSelector, RWDBUpdater, RWDBInserter, and RWDBDeleter correspond to the basic database operations select, update, insert, and delete respectively. RWDBSelectorBase and RWDBCompoundSelector are related to these.
• RWDBResult, RWDBReader, and RWDBCursor are used to process results.
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);
• Additional classes in this category include RWDBAssignment, RWDBCriterion, RWDBCollectableExpr, RWDBBoundExpr, and RWDBJoinExpr. Chapter 5, “The Data Manipulation Classes,” contains more examples of using these classes.
• 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 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 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.
• Data callback classes RWDBCharCallback, RWDBUChar16Callback, and RWDBBinaryCallback, define interfaces for specifying data callback methods.
• Class RWDBMultiRow adds row semantics to collections of RWDBTBuffers.
The Open SQL interface is described in detail in Chapter 14, “Defining Open SQL,” and Chapter 15, “Using the Open SQL Classes.”
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.
• Classes RWDBMemTable, RWDBRow, and RWDBTPtrMemTable<T,C> provide ways to store relational data in program memory.
— RWDBMemTable is a standard version that holds RWDBValue types.
— RWDBRow is a single row of an RWDBMemTable.
— RWDBTPtrMemTable<T,C> uses templates that hold user-defined types.
• 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 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, “Database and Connection Callbacks.” Detailed information for each class is in the SourcePro API Reference Guide.