RWDBTracer
Module: DB Interface Module Group: Utility and Diagnostics Classes
Does not inherit
- Local Index
- Synopsis
- Description
- Example
- Related Classes
- Public Enum
- Public Constructors
- Public Member Operators
- Public Member Functions
Local Index
Members
|
acquire() flag() isOn() |
isValid() operator<<() operator=() |
release() RWDBTracer() setOff() |
setOn() stream() TraceFlag |
Synopsis
#include <rw/db/tracer.h>
#include <fstream.h>
ofstream strm("trace.trc");
RWDBTracer& tracer = myDbase.tracer();
tracer.setOn(RWDBTracer::SQL);
tracer.stream(strm);
Description
Class RWDBTracer provides a runtime trace facility for DB Interface Module 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 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 insure that the associated ostream referenced by the RWDBTracer remains in scope while the RWDBTracer is set on.
Example
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.
Related Classes
RWDBDatabase instances provide access to their RWDBTracers.
Public Enum
enum TraceFlag { ZERO = 0, SQL = 1, BoundBuffers = 2, NoPlaceHoderSQL = 4, ThreadId = 8 };
SQL tracing results in a trace of all SQL sent to the database through the traced object.
BoundBuffers tracing results in a trace of all the data sent to the database in input-bound buffers.
NoPlaceHolderSQL also results in a trace of all SQL sent to the database through the traced object, except that any placeholders in the SQL are replaced 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 single-threaded builds, this setting does nothing. By default, ThreadID is OFF.
This enum tells an RWDBTracer what to trace.
Public Constructors
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.
Public Member Operators
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<< (long long arg); RWDBTracer& operator<< (unsigned long long arg); RWDBTracer& operator<< (float value); RWDBTracer& operator<< (double value); RWDBTracer& operator<< (long double arg); 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, 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);
Public Member Functions
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.
unsigned flag() const;
Returns a bit-mask representing the categories of tracing currently enabled.
bool isOn(TraceFlag flag) const;
Returns true if the trace category represented by flag is currently enabled, otherwise returns false.
bool 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. The DB Interface Module does not check strm for validity. Returns a reference to self.
TraceFlag setOff(TraceFlag);
Removes the categories represented by flags from those categories currently being traced by self. Returns the new bit-mask of traced categories.
TraceFlag setOn(TraceFlag);
Adds the categories represented by flags to those categories currently being traced by self. Returns the new bit-mask of traced categories.
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.