This section examines the Tutorial Two program you just ran. Its purpose is to write the mailing labels for all customers who are more than seven days overdue to a file called t2out.txt.
This code sample shows the main routine for the tutorial. The line numbers correspond to the comments that follow the code.
#include <rw/db/db.h> //1
#include "conrep.h" //2
#include "rentrep.h" //3
#include "tututil.h" //4
int main(int argc, char** argv) //5
{
associateStreams("", "t2out.txt", "t2err.txt");
RWDBManager::setErrorHandler (outputStatus);
RWCString serverType, serverName, userName,
password, databaseName, pstring;
initializeDatabaseArguments(argc, argv, serverType,
serverName, userName, password,
databaseName, pstring); //5
RWDBDatabase aDB = RWDBManager::database
(serverType, serverName, userName, password,
databaseName, pstring); //6
VVContactRepository customerPool (aDB,
customerTableName); //7
VVRentalTransactionRepository rentalTransactions
(aDB, rentalTableName); //8
RWDBColumn customerID = customerPool.idColumn(); //9
RWDBColumn rentalCustomerID =
rentalTransactions.customeridColumn(); //10
RWDBColumn dueDate =
rentalTransactions.dueDateColumn(); //11
RWDateTime aWeekAgo(9,6,2000); //12
aWeekAgo = aWeekAgo - (7 * RWDateTime::millisecsInDay); //13
customerPool.mailingLabels (outStream,
customerID == rentalCustomerID &&
dueDate < aWeekAgo); //14
closeStreams ("", "t2out.txt", "t2err.txt");
return 0;
} //15
|
Here is a line-by-line description of the program:
| //1 | Include the declarations for the DB Interface Module classes used here. |
| //2 | Include the declaration of the class VVContactRepository. |
| //3 | Include the declaration of the class VVRentalTransactionRepository. |
| //4 | Include the declarations for the utility routines used by all the tutorials. |
| //5 | The code block at //5 is for initialization. These lines are common to all the tutorials and are explained in the comments in Section 17.5.1, "The Main Routine." |
| //6 | Here an actual connection to a database server is established. The variable aDB will serve as a means to access the database defined by arguments to the RWDBManager::database() function. |
| //7 | An instance of the class VVContactRepository is created on this line. The first argument, aDB, identifies the database in which the instance's data resides. The second argument identifies the name of the specific table that holds the customer information. This constructor was explained in detail in Tutorial One. |
| //8 | An instance of the class VVRentalTransactionRepository is created on this line. The first argument, aDB, identifies the database in which instance's data resides. The second argument identifies the specific table that holds the rental transaction information. The constructor invoked here is quite simple and parallels the VVContactRepository constructor. |
| //9 | Here an instance of RWDBColumn that represents the ID column of the customer table is created. This instance will be used in creating a predicate to be used in a criterion for the selection. The idColumn() member function of the class VVContactRepository returns the column instance created in the VVContactRepository constructor. |
| //10 | Here an instance of RWDBColumn representing the customerID column of the rental transaction table is created. The customerIDColumn() member function of the class VVRentalTransactionRepository returns the column instance created in the VVRentalTransactionRepository constructor. |
| //11 | Here an instance of RWDBColumn representing the dueDate column of the rental transaction table is created. |
| //12 | This instance of RWDateTime is initialized to June 9th, 2000. |
| //13 | Subtracting seven days yields the date a week ago. |
| //14 | Here the mailingLabels() member function of VVContactRepository is executed. It accepts a reference to an output stream and an RWDBCriterion. The criterion is created anonymously by using overloaded relational operators on RWDBColumn instances. The result is the predicate that will be used in selecting the appropriate data from the customer table. |
| //15 | Destructors for all the objects are called here. The database closes automatically when its destructor is called. |
The invocation of the mailingLabels() member function on //18 above does most of the work in this tutorial. The source code of this member function, from the file conrep.cpp is shown here:
VVContactRepository&
VVContactRepository::mailingLabels (ostream& o,
const RWDBCriterion& criterion) //1
{
RWDBReader aReader = reader(criterion); //2
VVContact aContact; //3
while (aReader()) { //4
aReader >> aContact; //5
aContact.mailingLabel (o); //6
o << endl << endl; //7
}
return *this; //8
}
|
| //1 | This line defines the mailingLabels() member function for the class VVContactRepository. It receives an output stream as its first argument and an RWDBCriterion as its second argument. |
| //2 | The reader() member function of the class VVContactRepository is invoked here. It receives an RWDBCriterion as its argument and returns an RWDBReader. This reader is associated with a stream of information coming from the server that returns only the records that match the criterion. The reader() method is described in detail in Section 18.5.3 below. |
| //3 | The database table used in this tutorial has fields that match the instance variables in the class VVContact. This routine is about to start reading data from the table, and an instance of VVContact is a made-to-order place to store information from the table. This line creates an instance of VVContact to serve as a temporary variable for storing a single row from the table. |
| //4 | A reader is like an iterator. It must be advanced to the next row. Invoking the reader with the operator() member function advances the reader to the next row. If there are no more rows, then operator() returns a zero value and the loop terminates. |
| //5 | A reader is also like a stream. Here an entire row of data flows from the reader into the instance of VVContact. An explanation of this can be found in Section 17.5.4, "operator>>() for VVContact." |
| //6 | Since the instance of VVContact is complete, its own member functions can be called. The mailingLabel() member function simply outputs the instance variables for this customer in a form acceptable to the U.S. Postal Service. |
| //7 | The mailing labels need to be delimited in some manner, so we add two blank lines. |
| //8 | This routine needs to return an instance of VVContactRepository, so it returns itself. At this point, destructors for the VVContact instance and the RWDBReader instance are called. There were no pending rows from the RWDBReader. If there were, they would have been quietly and automatically discarded. |
Line //2 above invokes the reader() member function of VVContactRepository. The definition of the function called on //2 is shown below. This function actually creates the query and submits it to the database. It then returns an RWDBReader instance that can be used to get results back from the server.
RWDBReader
VVContactRepository::reader(const RWDBCriterion& criterion) //1
{
RWDBSelector s = aDB_.selector(criterion); //2
s.distinct(); //3
s << table_; //4
s.orderBy(nameColumn_); //5
return s.reader(); //6
}
|
| //1 | This line defines the reader() member function for the class VVContactRepository. It accepts one argument: a criterion to be used in determining which records to return from the customer table. | |
| //2 | s is an instance of RWDBSelector, an encapsulation of an SQL SELECT expression. It is produced and therefore associated with an instance of RWDBDatabase. This particular instance of RWDBDatabase, aDB_, was saved by the VVContactRepository constructor. In RWDBSelector's constructor, it uses one argument. This argument represents the predicate to be used in the WHERE clause of the select expression. In this case, the RWDBCriterion passed in eventually translates into a predicate that is functionally equivalent to:
| |
| //3 | This line adds an additional requirement that all results must be distinct; in other words, no duplicates should be returned. This is added because only a single row is required for each contact selected even if the contact has more than one rental transactions past due. This is functionally equivalent to: SELECT DISTINCT ... | |
| //4 | An RWDBSelector instance can select a variable number of columns or expressions. To reflect this indeterminate number of arguments, operator<<() was chosen to specify the SELECT clause. Instances of RWDBColumn can be shifted into the selector. In this case, all the columns are selected by shifting an RWDBTable instance into the selector. Here table_ is the RWDBTable instance associated with the customer table saved by the VVContactRepository constructor. This is equivalent to an SQL SELECT * expression. | |
| //5 | To sort the mailing labels in alphabetical order, the selector is instructed to orderBy() the column in which the customer's name is stored. This column was stored by the constructor in the nameColumn_ variable. This is equivalent to the SQL ORDER BY NAME. | |
| //6 | Fetching an instance of RWDBReader from a selector submits the query to the database. The selector has sufficient information to generate the appropriate SQL statement. The reader created here by the RWDBSelector instance is returned immediately by this member function. |
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.