asString() Methods in the Data Manipulation Classes

SourcePro : DB Interface Module User’s Guide : PART II Using the Basic Features : The Data Manipulation Classes : asString() Methods in the Data Manipulation Classes

The asString() methods in RWDBInserter, RWDBUpdater, RWDBDeleter, RWDBSelector and RWDBCompoundSelector provide the SQL representation of self. Note that these methods do not actually access the database, so there is no performance hit.

Each class contains these asString() methods:

RWCString asString() const;

RWCString asString( RWBoolean verbose ) const;

RWCString asString(const RWDBConnection& conn) const;

RWCString asString(const RWDBConnection& conn, RWBoolean verbose) const;

The first two methods return the SQL statement generated by the DB Interface Module when the DML operation would be executed with an implicit RWDBConnection. The last two methods return the SQL statement when the DML operation would be executed with an explicit RWDBConnection that is passed as a parameter.

The output may differ between implicit and explicit connections depending on the time zone settings on those connections. Implicit connections inherit the time zone setting from the producer RWDBDatabase instance, while explicit connections may have their own time zone setting. See RWDateTime for how to set the time zone on an RWDBDatabase or an RWDBConnection.

The SQL statement that is returned may have either of the following formats:

The actual SQL statement sent to the database for execution, containing either placeholders or bound data

The statement produced by replacing the placeholders in the original SQL statement with the bound data values

The following two methods return a string that depends on the verboseAsString() setting of the related RWDBDatabase instance. See RWDBDatabase for more information on the verboseAsString() method.

RWCString asString() const;

RWCString asString(const RWDBConnection& conn) const;

The next two methods return a string that depends on the verbose parameter and are therefore independent of the verboseAsString() setting of the RWDBDatabase instance.

RWCString asString( RWBoolean verbose ) const;

RWCString asString(const RWDBConnection& conn, RWBoolean verbose) const;

For more information on the asString() methods and their application, see RWDBInserter, RWDBUpdater, RWDBDeleter, RWDBSelector, and RWDBCompoundSelector in the SourcePro API Reference Guide.

The following table and example illustrate the behavior of the asString() method given various settings.

Table 8 – Output of asString() in various true/ false scenarios
The asString() method called	Setting of RWDBDatabase::verboseAsString()	Generated Output
asString(false)	true or false	SQL as sent to the database
asString(true)	true or false	Placeholders in the SQL replaced by bound values
asString()	true	Placeholders in the SQL replaced by bound values
asString()	false	SQL as sent to the database

Example 12 – asString() Method

RWDBTable table = myDbase.table("testtable");

RWDBInserter insert = table.inserter();

int aInt = 10;

RWCString aString("Hello");

insert << aInt << aString; // 1

myDbase.verboseAsString(false); // 2

std::cout << "First Output : " << insert.asString(true) << std::endl; // 3

std::cout << "Second Output: " << insert.asString(false) << std::endl; // 4

std::cout << "Third Output : " << insert.asString() << std::endl; // 5

myDbase.verboseAsString(true); // 6

std::cout << "Fourth Output: " << insert.asString(true) << std::endl; // 7

std::cout << "Fifth Output : " << insert.asString(false) << std::endl; // 8

std::cout << "Sixth Output : " << insert.asString() << std::endl; // 9

Output

First Output : INSERT testtable VALUES ( 10, 'Hello' )

Second Output: INSERT testtable VALUES ( @c0, @c1 )

Third Output : INSERT testtable VALUES ( @c0, @c1 )

Fourth Output: INSERT testtable VALUES ( 10, 'Hello' )

Fifth Output : INSERT testtable VALUES ( @c0, @c1 )

Sixth Output : INSERT testtable VALUES ( 10, 'Hello' )

//1 Adds an integer and an RWCString to the inserter.

//2 Sets the verboseAsString() setting of the producing RWDBDatabase myDbase to false.

//3 The verboseAsString() setting is ignored, and any placeholders in the returned SQL are replaced with the data.

//4 The verboseAsString() setting is ignored, and the SQL returned is the same as that which would be sent to the database if the RWDBInserter object insert were executed.

//5 The verboseAsString() setting is used. Since the setting is false, the SQL returned is the same as that which would be sent to the database if the RWDBInserter object insert were executed.

//6 Sets the verboseAsString( setting of the producing RWDBDatabase, myDbase, to true.

//7 The RWDBDatabase::verboseAsString() setting is ignored, and any placeholders in the returned SQL are replaced with the data.

//8 The verboseAsString() setting is ignored, and the SQL returned is the same as that sent to the database when insert is executed.

//9 The verboseAsString() setting is used. Since the setting is true, any placeholders in the returned SQL will be replaced with the data.

NOTE: A similar enhancement in RWDBTracer allows traced SQL statements with the placeholders to be replaced by the bound data values. See RWDBTracer in the SourcePro API Reference Guide for more information.