RWDBTracer Class Reference
[Utilities and Diagnostics]

Provides a runtime trace facility for DB Interface Module applications. More...

#include <rw/db/tracer.h>

List of all members.

Public Types
enum	TraceFlag { , SQL, BoundBuffers, NoPlaceHolderSQL, ThreadID }
Public Member Functions
	RWDBTracer ()
	RWDBTracer (const RWDBTracer &aTrace)
RWDBTracer &	operator= (const RWDBTracer &aTrace)
RWDBTracer &	stream (std::ostream &strm)
std::ostream &	stream ()
unsigned	setOn (TraceFlag flags)
bool	isOn (TraceFlag flag) const
unsigned	flag () const
unsigned	setOff (TraceFlag flags)
void	acquire () const
void	release () const
RWDBTracer &	operator<< (char arg)
RWDBTracer &	operator<< (signed char arg)
RWDBTracer &	operator<< (unsigned char arg)
RWDBTracer &	operator<< (short arg)
RWDBTracer &	operator<< (unsigned short arg)
RWDBTracer &	operator<< (int arg)
RWDBTracer &	operator<< (unsigned int arg)
RWDBTracer &	operator<< (long arg)
RWDBTracer &	operator<< (unsigned long arg)
RWDBTracer &	operator<< (long long arg)
RWDBTracer &	operator<< (unsigned long long arg)
RWDBTracer &	operator<< (float arg)
RWDBTracer &	operator<< (double arg)
RWDBTracer &	operator<< (long double arg)
RWDBTracer &	operator<< (const char *str)
RWDBTracer &	operator<< (const signed char *arg)
RWDBTracer &	operator<< (const unsigned char *arg)
RWDBTracer &	operator<< (void *arg)
RWDBTracer &	operator<< (std::ostream &(*f)(std::ostream &))
RWDBTracer &	operator<< (std::ios &(*f)(std::ios &))
bool	isValid ()

---

Detailed Description

Class RWDBTracer provides a runtime trace facility for DB Interface Module applications. RWDBTracer objects can be turned ON or OFF, and they can be told what to trace. The default output for an RWDBTracer is the std::ostream std::clog. The output from an RWDBTracer can be redirected to an std::ostream.

A database object of the DB Interface Module contains an RWDBTracer. Consequently, enabling tracing on an RWDBDatabase, for example, produces trace output for all objects produced by that RWDBDatabase.

It is the application's responsibility to ensure that the associated std::ostream referenced by the RWDBTracer remains in scope while the RWDBTracer is set ON.

Synopsis

 #include <rw/db/tracer.h>
 #include <fstream>

 std::ofstream strm("trace.trc");
 RWDBTracer& tracer = myDbase.tracer();
 tracer.setOn(RWDBTracer::SQL);
 tracer.stream(strm);

Related Classes

RWDBDatabase instances provide access to its RWDBTracer.

Examples

 RWDBTracer& tracer = myDbase.tracer();
 tracer.setOn(RWDBTracer::SQL);
 std::ofstream strm("trace.out");
 tracer.stream(strm);

---

Member Enumeration Documentation

enum RWDBTracer::TraceFlag

Defines the values that tell an RWDBTracer what to trace.

Enumerator:

SQL	Traces all SQL sent to the database through the traced object
BoundBuffers	Traces all the data sent to the database in input-bound buffers
NoPlaceHolderSQL	Traces all SQL sent to the database through the traced object, and replaces any placeholders in the SQL with their contents. When placeholders are bound as arrays, the SQL is repeated for each value in the arrays
ThreadID	If turned ON in multithreaded builds, prints the thread id of the execution thread in the tracer stream. The thread id is printed for all three types of tracer output. For singlethreaded builds, this setting does nothing. By default, ThreadID is OFF

---

Constructor & Destructor Documentation

RWDBTracer::RWDBTracer

(

)

Default constructor that produces an RWDBTracer not associated with any object. To obtain useful trace information, get an RWDBTracer reference from an RWDBDatabase.

RWDBTracer::RWDBTracer

(

const RWDBTracer &

aTrace

)

Copy constructor. RWDBTracer objects are copied by value.

---

Member Function Documentation

void RWDBTracer::acquire

(

)

const

Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object.

Note:

In singlethreaded builds, this function evaluates to a no-op.

unsigned RWDBTracer::flag

(

)

const

Returns a bit-mask representing the categories of tracing currently enabled.

bool RWDBTracer::isOn

(

TraceFlag

flag

)

const

Returns true if the trace category represented by flag is currently enabled, otherwise returns false.

bool RWDBTracer::isValid

(

)

Returns false if the attached std::ostream encounters an EOF or if the bad bit has been set, otherwise true.

RWDBTracer& RWDBTracer::operator<<

(

std::ios &(*)(std::ios &)

f

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

std::ostream &(*)(std::ostream &)

f

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

void *

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

const unsigned char *

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

const signed char *

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

const char *

str

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

long double

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

double

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

float

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

unsigned long long

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

long long

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

unsigned long

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

long

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

unsigned int

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

int

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

unsigned short

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

short

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

unsigned char

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

signed char

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator<<

(

char

arg

)

Values may be streamed out through an RWDBTracer, much as through a std::ostream, allowing applications to annotate the trace output. Structured objects may be streamed out by defining a function of the form:

 RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);

RWDBTracer& RWDBTracer::operator=

(

const RWDBTracer &

aTrace

)

Assignment operator. RWDBTracer objects are copied by value.

void RWDBTracer::release

(

)

const

Releases a previously acquired mutex. This function can be called from a const object.

Note:

In singlethreaded builds, this function evaluates to a no-op.

unsigned RWDBTracer::setOff

(

TraceFlag

flags

)

Removes the categories represented by flags from those categories currently being traced by self. Returns the new bit-mask of traced categories.

unsigned RWDBTracer::setOn

(

TraceFlag

flags

)

Adds the categories represented by flags to those categories currently being traced by self. Returns the new bit-mask of traced categories.

std::ostream& RWDBTracer::stream

(

)

Returns a reference to the stream currently attached to self.

RWDBTracer& RWDBTracer::stream

(

std::ostream &

strm

)

Directs all subsequent trace output to the supplied strm. The DB Interface Module does not check strm for validity. Returns a reference to self.