Trace

The Trace object allows the Java program to log trace points and diagnostic messages. This information helps reproduce and diagnose problems.

Note: You can also set tracing by using the trace system properties.

The Trace class logs the following categories of information:

Information category Description
Conversion Logs character set conversions between Unicode and code pages. This category should be used only by the IBM Toolbox for Java classes.
Datastream Logs the data that flows between the iSeries and the Java program. This category should be used only by the IBM Toolbox for Java classes.
Diagnostic Logs state information.
Error Logs additional errors that cause an exception.
Information Traces the flow through a program.
Begin changePCML This category is used to determine how PCML interprets the data that is sent to and from the server.End change
Proxy This category is used by IBM Toolbox for Java classes to log data flow between the client and the proxy server.
Warning Logs information about errors the program was able to recover from.
All This category is used to enable or disable tracing for all of the above categories at once. Trace information can not be directly logged to this category.

The IBM Toolbox for Java classes also use the trace categories. When a Java program enables logging, IBM Toolbox for Java information is included with the information that is recorded by the application.

You can enable the trace for a single category or a set of categories. Once the categories are selected, use the setTraceOn method to turn tracing on and off. Data is written to the log using the log method.

You can send trace data for different components to separate logs. Trace data, by default, is written to the default log. Use component tracing to write application-specific trace data to a separate log or standard output. By using component tracing, you can easily separate trace data for a specific application from other data.

Excessive logging can impact performance. Use the isTraceOn method to query the current state of the trace. Your Java program can use this method to determine whether it should build the trace record before it calls the log method. Calling the log method when logging is off is not an error, but it takes more time.

The default is to write log information to standard out. To redirect the log to a file, call the setFileName() method from your Java application. In general, this works only for Java applications because most browsers do not give applets access to write to the local file system.

Logging is off by default. Java programs should provide a way for the user to turn on logging so that it is easy to enable logging. For example, the application can parse for a command line parameter that indicates which category of data should be logged. The user can set this parameter when log information is needed.

The following examples show how to use the Trace class.

Example 1: The following is an example of how to use the setTraceOn method, and how to write data to a log by using the log method.

     // Enable diagnostic, information, and warning logging.
     Trace.setTraceDiagnosticOn(true);
     Trace.setTraceInformationOn(true);
     Trace.setTraceWarningOn(true);
 
     // Turn tracing on.
     Trace.setTraceOn(true);
 
     // ... At this point in the Java program, write to the log.
     Trace.log(Trace.INFORMATION, "Just entered class xxx, method xxx");

     // Turning tracing off.
     Trace.setTraceOn(false);

Example 2: The following examples show how to use trace. Method 2 is the preferable way to write code that uses trace.

     // Method 1 - build a trace record
     // then call the log method and let the trace class determine if the
     // data should be logged. This will work but will be slower than the
     // following code.
     String traceData = new String("Just entered class xxx, data = ");
     traceData = traceData + data + "state = " + state;
     Trace.log(Trace.INFORMATION, traceData);
 
     // Method 2 - check the log status before building the information to
     // log. This is faster when tracing is not active.
     if (Trace.isTraceOn() && Trace.isTraceInformationOn())
     {
        String traceData = new String("just entered class xxx, data = ");
        traceData = traceData + data + "state = " + state;
        Trace.log(Trace.INFORMATION, traceData);
     }

Example 3: The following shows how you can use component tracing.

     // Create a component string. It is more efficient to create an
     // object than many String literals.
     String myComponent1 = "com.myCompany.xyzComponent";
     String myComponent2 = "com.myCompany.abcComponent";
         
     // Send Toolbox and the component trace data each to separate files.
     // The Toolbox trace will contain all trace information, while each
     // component log file will only contain trace information specific to
     // that component.  If a Trace file is not specified, all trace data
     // will go to standard out with the component specified in front of
     // each trace message.

     // Trace.setFileName("c:\\bit.bucket");       
     // Trace.setFileName(myComponent1, "c:\\Component1.log");
     // Trace.setFileName(myComponent2, "c:\\Component2.log");

     Trace.setTraceOn(true);             // Turn trace on.
     Trace.setTraceInformationOn(true);  // Enable information messages. 
         
     // Log component specific trace data or general toolbox
     // trace data.
    
     Trace.setFileName("c:\\bit.bucket");       
     Trace.setFileName(myComponent1, "c:\\Component1.log");

The results of the example, if you do not specify any trace files, look like this:

     Toolbox for Java - Version 5 Release 1 Modification level 0
     [com.myCompany.xyzComponent] Tue Oct 24 16:02:44 CDT 2000 I am here
     [com.myCompany.abcComponent] Tue Oct 24 16:02:44 CDT 2000 I am there
     Tue Oct 24 16:02:44 CDT 2000 I am everywhere