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 Section 3.1.6, "Open SQL Classes,", and Chapter 15, "Using the Open SQL Classes." This chapter summarizes the different kinds of classes in the DB Interface Module.
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. This class is deprecated. Use class RWDateTime instead.
RWDateTime: Date and Time values.
RWDecimalPortable: Arbitrary precision decimal fraction data.
RWDBBlob: Binary Large Objects (Blobs).
RWDBDateTime: Date and time values. This class is deprecated. Use class RWDateTime instead.
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 data type normalization. It is visible to your applications as the data type of a single cell of an RWDBRow or an RWDBMemTable. It is useful for applications that must manipulate data without knowing its type.
RWTime: Time values. This class is deprecated. Use class RWDateTime instead.
RWWString: Wide character strings.
RWBasicUString: UTF-16 Unicode strings.
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.
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, RWDBStoredProc, RWDBForeignKey, and RWDBForeignKeyList represent the database objects that their names suggest.
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.
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.
Class RWDBExpr is a base class for a family of classes in the DB Interface Module that allow 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 C++ API Reference Guide.
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 data type 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.
Classes RWDBStringVector, RWDBStringVectorElement, RDBBinaryVector, RWDBBinaryVectorElement, RWDBDecimalVector, RWDBDecimalVectorElement, RWDBDateVector, RWDBVendorDate and RWDBVector<T> are deprecated. Please use the template class RWDBTBuffer<T> instead.
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."
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 C++ API Reference Guide and the DB Access Module guides contain more information on all the classes described here.
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.
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.