ITrace

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:

Specifying any of the preceding locations has the side effect of turning tracing on.

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:

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.

AIX Considerations

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.

OS/2 Considerations

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.


ITrace - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class by using the default constructor and the provided destructor.


[view class]
~ITrace
public:
~ITrace()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ITrace
public:
ITrace(const char* traceName = 0, long lineNumber = 0)
Construct an ITrace object using this default constructor. If you do not specify the optional values, this constructor creates an ITrace object, but no logging occurs on construction or destruction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Debug Support

Debug support methods.


[view class]
writeDebugLocation
public:
static void writeDebugLocation( const char* str, const IExceptionLocation& location )
Writes the passed debug location information out.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Enabling and Disabling

Use these members to enable or disable tracing, as well as to query whether tracing is on.


[view class]
disableTrace
public:
static void disableTrace()

Disables trace entries from being written.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableTrace
public:
static void enableTrace()

Enables trace entries to be written.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isTraceEnabled
public:
static bool isTraceEnabled()

Determines whether tracing is currently enabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Format

Use these members to enable, disable, and query the formatting options for writing trace output.


[view class]
disableWriteLineNumber
public:
static void disableWriteLineNumber()

Disables the tracing of line number information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disableWritePrefix
public:
static void disableWritePrefix()

Disables the writing of the process ID, the thread ID, and the output line number to trace.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableWriteLineNumber
public:
static void enableWriteLineNumber()

Enables the tracing of line number information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableWritePrefix
public:
static void enableWritePrefix()

Enables the writing of the process ID, the thread ID, and the output line number to trace.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isWriteLineNumberEnabled
public:
static bool isWriteLineNumberEnabled()

Determines whether line numbers are currently being written.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isWritePrefixEnabled
public:
static bool isWritePrefixEnabled()

Determines whether the line count prefix is being written.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Output Operations

Use these members to do the following:


[view class]
traceDestination
public:
static ITrace::Destination traceDestination()

Returns the trace output destination for this trace object. The returned value is an enumerator provided by ITrace::Destination.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
write

Writes the specified text.


Overload 1
public:
static void write(const IString& text)
text
The text to write as an IString.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static void write(const char* text)
text
The text to write as a character string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeToFile
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeToQueue
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In AIX, this member function is equivalent to writeToStandardOutput.


[view class]
writeToStandardError
public:
static void writeToStandardError()

Sets the location for output to the standard error stream.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeToStandardOutput
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: STDOUT is a synonym for OUT.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeFormattedString
protected:
static void writeFormattedString( const IString& string, char* marker )

Writes the trace data after formatting, which includes the following:

string
Any trace information you want to write.
marker
When the Open Class Library uses this function, it specifies a character to mark, or distinguish, whether the trace statement is entering (+) or exiting (-) a function. You can specify marker for any purpose.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeString
protected:
static void writeString(char* text)

Writes to the output device without formatting.

text
Any trace information you want to write.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Thread ID

Use these members to query the thread ID.


[view class]
threadId
protected:
static unsigned long threadId()

Returns the current thread identifier.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In environments that do not support kernel threads, this function always returns a 1.


ITrace - Enumerations


[view class]
Destination
enum Destination { queue, 
                   standardError, 
                   standardOutput, 
                   file }

These enumerators specify the destination of the trace data:

queue
Sends the trace data to the queue.
standardError
Sends the trace data to the standard error stream (stderr).
standardOutput
Sends the trace data to the standard output (stdout).
file
Sends the trace data to a file specified by environment variable ICLUI_TRACEFILE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support the queue enumerator. If the trace destination is queue, tracing goes to stdout.


ITrace - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data