The ITrace class provides module tracing within the Open Class Library. Whenever an exception is thrown by the library, trace records are output with information about the exception. You can use the ICLUI_TRACE and ICLUI_TRACETO environment variables to redirect the trace output to a file. The output trace records contain the following:
By default, the library disables tracing. You can set tracing on by entering ICLUI_TRACE=ON in the environment.
Also, by default, the library attaches a prefix to the trace entry containing a sequence number followed by the process and thread where the trace call occurred. You can remove prefix area tracing by entering ICLUI_TRACE=NOPREFIX in the environment. Doing so has the side effect of turning tracing on.
You can set the output location of tracing by entering one of the following in the environment:
In addition to turning the trace options on and off in the environment, the library also provides static member functions to do the same thing under program control.
Tracing can be set on and off using the static functions enableTrace() and disableTrace().
The output location of tracing can be changed to stderr or stdout by using the static functions writeToStandardError() or writeToStandardOutput().
Prefix area tracing can be enabled or disabled by using the static function enableWritePrefix(), or disableWritePrefix().
The library supports trace input as IStrings or character arrays, and the library automatically adds a line feed on all trace calls.
To enable you to compile the trace calls in and out of your code, the Open Class Library provides the following sets of macros for tracing modules and data:
IMODTRACE_RUNTIME() IFUNCTRACE_RUNTIME() ITRACE_RUNTIME()
IMODTRACE_DEVELOP() IFUNCTRACE_DEVELOP() ITRACE_DEVELOP()
IMODTRACE_ALL() IFUNCTRACE_ALL() ITRACE_ALL()
The IMODTRACE version of the macros accepts as input a module name that it uses for construction and destruction tracing.
The IFUNCTRACE version of the macros accepts no input and uses the predefined identifier __FUNCTION__ for construction and destruction tracing.
The ITRACE version of the macros accepts a text string to be written out.
The default output location of tracing is standardOutput. Setting the output location of tracing to queue has the same effect in X-Motif as setting it to standardOutput.
In OS/2, the library supports the environment variables ICLUI TRACE and ICLUI TRACETO, in addition to ICLUI_TRACE and ICLUI_TRACETO.
The default output location of tracing is the OS/2 queue \\QUEUES\\PRINTF32. You can display this queue using the program PMPRTF32.EXE.
Constructors & DestructorYou can construct and destruct objects of this class by using the default constructor and the provided destructor.
![]() |
public:
~ITrace()
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
ITrace(const char* traceName = 0, long lineNumber = 0)
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Debug SupportDebug support methods.
![]() |
public:
static void writeDebugLocation( const char* str, const IExceptionLocation& location )
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Enabling and DisablingUse these members to enable or disable tracing, as well as to query whether tracing is on.
![]() |
public:
static void disableTrace()
Disables trace entries from being written.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void enableTrace()
Enables trace entries to be written.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static bool isTraceEnabled()
Determines whether tracing is currently enabled.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
FormatUse these members to enable, disable, and query the formatting options for writing trace output.
![]() |
public:
static void disableWriteLineNumber()
Disables the tracing of line number information.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void disableWritePrefix()
Disables the writing of the process ID, the thread ID, and the output line number to trace.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void enableWriteLineNumber()
Enables the tracing of line number information.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void enableWritePrefix()
Enables the writing of the process ID, the thread ID, and the output line number to trace.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static bool isWriteLineNumberEnabled()
Determines whether line numbers are currently being written.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static bool isWritePrefixEnabled()
Determines whether the line count prefix is being written.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Output OperationsUse these members to do the following:
![]() |
public:
static ITrace::Destination traceDestination()
Returns the trace output destination for this trace object. The returned value is an enumerator provided by ITrace::Destination.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
Writes the specified text.
public:
static void write(const IString& text)
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
static void write(const char* text)
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void writeToFile()
Set the location for output to a file. Using this function is equivalent to setting the environment variable ICLUI_TRACETO=FILE.
In order for this to work another environment variable ICLUI_TRACEFILE needs to be set.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void writeToQueue()
Sets the location for output to \\QUEUES\\PRINTF32 in the OS/2 environment.
Sets the location for output to \\.\MAILSLOT\PRINTF32 in the Win32 environment.
Sets the location for output to Job log in the OS/400 environment.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
In AIX, this member function is equivalent to writeToStandardOutput.
![]() |
public:
static void writeToStandardError()
Sets the location for output to the standard error stream.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
public:
static void writeToStandardOutput()
Sets the location for output to the standard output stream.
Using this function is equivalent to setting the environment variable
ICLUI_TRACETO=OUT.
Note:
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
protected:
static void writeFormattedString( const IString& string, char* marker )
Writes the trace data after formatting, which includes the following:
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
![]() |
protected:
static void writeString(char* text)
Writes to the output device without formatting.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Thread IDUse these members to query the thread ID.
![]() |
protected:
static unsigned long threadId()
Returns the current thread identifier.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
In environments that do not support kernel threads, this function always returns a 1.
![]() |
enum Destination { queue,
standardError,
standardOutput,
file }These enumerators specify the destination of the trace data:
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
AIX does not support the queue enumerator. If the trace destination is queue, tracing goes to stdout.