### 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:

  - Error message text
  - Error ID
  - Class name
  - Information from the class IExceptionLocation

  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:

  - ICLUI_TRACETO=STDERR for the standard error stream (stderr)
  - ICLUI_TRACETO=STDOUT for the standard output (stdout)
  - ICLUI_TRACETO=FILE for a file stream specified by the environment ICLUI_TRACEFILE
  - ICLUI_TRACETO=QUEUE for a queue
  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 library defines IC_TRACE_RUNTIME by default. The following macros are expanded:

            IMODTRACE_RUNTIME()  IFUNCTRACE_RUNTIME()  ITRACE_RUNTIME()

  - If you define IC_TRACE_DEVELOP, the following macros, in addition to the RUNTIME macros, are expanded:

            IMODTRACE_DEVELOP()  IFUNCTRACE_DEVELOP()  ITRACE_DEVELOP()

  - If you define IC_TRACE_ALL, the following macros, in addition to the RUNTIME and DEVELOP macros, are expanded:

            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.

#### 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.

~ITrace

      public:
      ~ITrace()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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.

disableTrace

      public:
      static void disableTrace()

  Disables trace entries from being written.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

enableTrace

      public:
      static void enableTrace()

  Enables trace entries to be written.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

disableWriteLineNumber

      public:
      static void disableWriteLineNumber()

  Disables the tracing of line number information.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

enableWriteLineNumber

      public:
      static void enableWriteLineNumber()

  Enables the tracing of line number information.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

isWriteLineNumberEnabled

      public:
      static bool isWriteLineNumberEnabled()

  Determines whether line numbers are currently being written.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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:

- Write trace data to the current trace location
- Query the current trace location
- Set the current trace location

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

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

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

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.

writeToStandardError

      public:
      static void writeToStandardError()

  Sets the location for output to the standard error stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

writeFormattedString

      protected:
      static void
        writeFormattedString( const IString& string,
                              char* marker )

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

  - Adding the prefix, if necessary
  - Updating any new lines embedded in the string to include the prefix
  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

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.

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None