| Data Types | |
| enum TraceFlag |
| Member Functions | |||
| acquire() flag() isOn() |
isValid() operator<<() operator=() |
release() setOff() setOn() |
stream() |
#include <rw/db/tracer.h>
#include <fstream.h>
ofstream strm("trace.trc");
RWDBTracer& tracer = myDbase.tracer();
tracer.setOn(RWDBTracer::SQL);
tracer.stream(strm);
Class RWDBTracer provides a runtime trace facility for DBTools.h++ applications. RWDBTracers can be turned on or off, and they can be told what to trace. The default output for an RWDBTracer is the stream clog. The output from an RWDBTracer can be redirected to an ostream.
A DBTools.h++ database object 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 insure that the associated ostream referenced by the RWDBTracer remains in scope while the RWDBTracer is set on.
Here is how to obtain a trace of all SQL sent through the RWDBDatabase myDbase, sending the output to the file "trace.out."
RWDBTracer& tracer = myDbase.tracer();
tracer.setOn(RWDBTracer::SQL);
ofstream strm("trace.out");
tracer.stream(strm);
Notice the declaration RWDBTracer& tracer. It would be ineffective to declare tracer as an RWDBTracer, rather than as an RWDBTracer reference. Doing so would result in a local copy of myDbase's tracer: the setOn() and stream() calls would have no effect on the database that we wished to trace.
RWDBDatabase instances provide access to their RWDBTracers.
enum TraceFlag { ZERO = 0, SQL = 1 };
This enum is used to tell an RWDBTracer what to trace. Currently the only traceable category is SQL. SQL tracing results in a trace of all SQL sent to the database through the traced object.
RWDBTracer();
The default constructor produces an RWDBTracer which is not associated with any object. To obtain useful trace information, get an RWDBTracer reference from an RWDBDatabase or RWDBConnection.
RWDBTracer(const RWDBTracer& tracer);
Copy constructor. RWDBTracers are copied by value.
RWDBTracer& operator=(const RWDBTracer& tracer);
Assignment operator. RWDBTracers are copied by value.
RWDBTracer& operator<< (char value); RWDBTracer& operator<< (unsigned char value); RWDBTracer& operator<< (short value); RWDBTracer& operator<< (unsigned short value); RWDBTracer& operator<< (int value); RWDBTracer& operator<< (unsigned int value); RWDBTracer& operator<< (long value); RWDBTracer& operator<< (unsigned long value); RWDBTracer& operator<< (float value); RWDBTracer& operator<< (double value); RWDBTracer& operator<< (const char* string); RWDBTracer& operator<< (void* value); RWDBTracer& operator<< (ostream& (_f)(ostream & ));
Values may be streamed out through an RWDBTracer, much as through an ostream, giving applications the opportunity to annotate the trace output. Structured objects may be streamed out by defining a function of the form:
RWDBTracer& operator<<(RWDBTracer& tracer, someStruct& s);
void 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 nonmultithreaded builds, this function evaluates to a no-op.
TraceFlag flag();
Returns a bit-mask representing the categories of tracing currently enabled.
RWBoolean isOn(TraceFlag flag);
Returns TRUE if the trace category represented by flag is currently enabled, otherwise returns FALSE.
RWBoolean isValid() const;
Returns TRUE if self's status is RWDBStatus::ok; otherwise returns FALSE.
void release() const;
Releases a previously acquired mutex. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.
ostream& stream();
Returns a reference to the stream currently attached to self.
RWDBTracer& stream(ostream& strm);
Directs all subsequent trace output to the supplied strm. DBTools.h++ does not check strm for validity. Returns a reference to self.
TraceFlag setOff(flags);
Removes the categories represented by flags from those categories currently being traced by self. Returns the new bit-mask of traced categories.
TraceFlag setOn(flags);
Adds the categories represented by flags to those categories currently being traced by self. Returns the new bit-mask of traced categories.
©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.