com.ibm.as400.access

Class Trace

  • All Implemented Interfaces:
    Runnable


    public class Trace
    extends Object
    implements Runnable
    Logs trace points and diagnostic messages. Each trace point and diagnostic message is logged by category. The valid categories are:
    • DATASTREAM
      This category is used by Toolbox classes to log data flow between the local host and the remote system. It is not intended for use by application classes.
    • DIAGNOSTIC
      This category is used to log object state information.
    • ERROR
      This category is used to log errors that cause an exception.
    • INFORMATION
      This category is used to track the flow of control through the code.
    • WARNING
      This category is used to log errors that are recoverable.
    • CONVERSION
      This category is used by Toolbox classes to log character set conversions between Unicode and native code pages. It is not intended for use by application classes.
    • PROXY
      This category is used by Toolbox classes to log data flow between the client and the proxy server. It is not intended for use by application classes.
    • PCML
      This category is used to determine how PCML interprets the data that is sent to and from the system.
    • JDBC
      This category is used to include JDBC data in the standard Toolbox trace.

    The caller can enable or disable all tracing or specific trace categories. Enabling or disabling one category does not affect other categories. Once appropriate category traces are enabled, trace must be turned on to get trace data. For example,

          // By default, trace is disabled for all categories and
          // tracing is off.
          ..
          Trace.setTraceErrorOn(true);          // Enable error messages
          Trace.setTraceWarningOn(true);        // Enable warning messages
    
          Trace.setTraceOn(true);               // Turn trace on for all
                                                // Enabled categories
    
          ..
          Trace.setTraceOn(false);              // Turn trace off
          ..
          Trace.setTraceOn(true);               // Turn trace back on
          ..
          Trace.setTraceInformationOn(true);    // Enable informational messages.
                                                // Since trace is still on, no
                                                // other action is required to
                                                // get this data
    
          ..
          Trace.setTraceWarningOn(false);       // Disable warning messages.  Since
                                                // trace is still on, the other
                                                // categories will still be logged
      
    The traces are logged to standard out by default. A file name can be provided to log to a file. File logging is only possible in an application as most browsers do not allow access to the local file system.

    Trace data can also be specified by component. Trace data is always written to the default log but component tracing provides a way to write trace data to a separate log.

    The following example logs data for Function123 into log file C:\Function123.log, and logs data for Function456 into log file C:\Function456.log. Data for these two components is also traced to the normal trace file (standard output in this case since that is the default for normal tracing). The result is three sets of data -- a file containing trace data for only Function123, a file containing trace data for only Function456, and standard output which records all trace data. In the example a Java String object is used to indicate the component, but any object can be used.

          // tracing is off by default
          ..
          String cmpF123 = "Function123";      // More efficient to create an object
          String cmpF456 = "Function456";      // than many String literals.
    
                                                 // Specify where data should go
                                                 // for the two components.
          Trace.setFileName(cmpF123, "C:\\Function123.log");
          Trace.setFileName(cmpF456, "C:\\Function456.log");
    
          Trace.setTraceInformationOn(true);     // Trace only the information category.
          Trace.setTraceOn(true);                // Turn tracing on.
          ..
          Trace.log(cmpF123, Trace.INFORMATION, "I am here");
          ..
          Trace.log(cmpF456, Trace.INFORMATION, "I am there");
          ..
          Trace.log(cmpF456, Trace.INFORMATION, "I am everywhere");
          ..
          Trace.setTraceOn(false);               // Turn tracing off.
      

    Component tracing provides an easy way to write application specific trace data to a log or standard output. Any application and the Toolbox classes can use trace to log messages. With component tracing, application data can be easily separated from other data. For example,

          String myComponent = "com.myCompany";      // More efficient to create an object
                                                     // than many String literals.
    
          Trace.setFileName("C:\\bit.bucket");       // Send default trace data to
                                                     // a file.
    
          Trace.setTraceInformationOn(true);         // Enable information messages.
          Trace.setTraceOn(true);                    // Turn trace on.
    
          ...
    
                                 // Since no file was specified, data for
                                 // myComponent goes to standard output.
                                 // Other information messages are sent to a file.
          Trace.log(myComponent, Trace.INFORMATION, "my trace data");
    
      

    Two techniques can be used to log information:

          ..
          // Let the Trace method determine if logging should occur
          Trace.log(Trace.INFORMATION, "I got here...");
          ..
          // Pre-determine if we should log.  This may be more efficient
          // if a lot of processing in needed to generate the trace data.
          if (Trace.isTraceOn() && Trace.isTraceInformationOn())
          {
                Trace.log(Trace.INFORMATION, "I got here...");
          }
      

    It is suggested that programs provide some mechanism to enable tracing at run-time, so that the modification and recompilation of code is not necessary. Two possibilities for that mechanism are a command line argument (for applications) or a menu option (for applications and applets).

    In addition, tracing can be set using the "com.ibm.as400.access.Trace.category" and "com.ibm.as400.access.Trace.file" system properties.

    Note: This class can exploit a standard Java Logger if one is defined in the JVM (per JSR 47, package java.util.logging, added in J2SE 1.4). See LOGGER_NAME.

    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int CONVERSION
      'Character set conversion' trace category.
      static int DATASTREAM
      'Data stream' trace category.
      static int DIAGNOSTIC
      'Diagnostic message' trace category.
      static int ERROR
      'Error message' trace category.
      static int INFORMATION
      'Information message' trace category.
      static int JDBC
      'JDBC' trace category.
      static String LOGGER_NAME
      Name of the instance of java.util.logging.Logger that the Toolbox uses.
      static int PCML
      'PCML' trace category.
      static int PROXY
      'Proxy' trace category.
      static int WARNING
      'Warning message' trace category.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      static String getFileName()
      Returns the trace file name.
      static String getFileName(Object component)
      Returns the trace file name for the specified component.
      static PrintWriter getPrintWriter()
      Returns the PrintWriter object.
      static PrintWriter getPrintWriter(Object component)
      Returns the print writer object for the specified component.
      static boolean isTraceAllOn()
      Indicates if all of the tracing categories are enabled.
      static boolean isTraceConversionOn()
      Indicates if character set conversion tracing is enabled.
      static boolean isTraceDatastreamOn()
      Indicates if data stream tracing is enabled.
      static boolean isTraceDiagnosticOn()
      Indicates if diagnostic tracing is enabled.
      static boolean isTraceErrorOn()
      Indicates if error tracing is enabled.
      static boolean isTraceInformationOn()
      Indicates if information tracing is enabled.
      static boolean isTraceJDBCOn()
      Indicates if JDBC tracing is enabled.
      static boolean isTraceOn()
      Indicates if overall tracing is enabled.
      static boolean isTraceOn(int category)
      Indicates if tracing is enabled for the specified category.
      static boolean isTracePCMLOn()
      Indicates if PCML tracing is enabled.
      static boolean isTraceProxyOn()
      Indicates if proxy tracing is enabled.
      static boolean isTraceThreadOn()
      Indicates if thread tracing is enabled.
      static boolean isTraceWarningOn()
      Indicates if warning tracing is enabled.
      static void log(int category, Object source, String message)
      Logs a message in the specified category.
      static void log(int category, Object source, String message, boolean value)
      Logs a message and a boolean value in the specified category.
      static void log(int category, Object source, String message, byte[] data)
      Logs a message and byte data in the specified category.
      static void log(int category, Object source, String message, int value)
      Logs a message and an integer value in the specified category.
      static void log(int category, Object source, String message, Throwable e)
      Logs a message in the specified category.
      static void log(int category, String message)
      Logs a message in the specified category.
      static void log(int category, String message, boolean value)
      Logs a message and a boolean value in the specified category.
      static void log(int category, String message, byte[] data)
      Logs a message and byte data in the specified category.
      static void log(int category, String message, byte[] data, int offset, int length)
      Logs a message and byte data in the specified category.
      static void log(int category, String message, int value)
      Logs a message and an integer value in the specified category.
      static void log(int category, String message, String value)
      Logs a message and a String value in the specified category.
      static void log(int category, String message, Throwable e)
      Logs a message in the specified category.
      static void log(int category, Throwable e)
      Logs a message in the specified category.
      static void log(Object component, int category, Object source, String message)
      Logs a message for the specified component for the specified category.
      static void log(Object component, int category, String message)
      Logs a message for the specified component for the specified category.
      static void log(Object component, int category, String message, boolean value)
      Logs a message and a boolean value in the specified category for the specified component.
      static void log(Object component, int category, String message, byte[] data)
      Logs a message and byte data in the specified category for the specified component.
      static void log(Object component, int category, String message, byte[] data, int offset, int length)
      Logs a message and byte data in the specified category for the specified component.
      static void log(Object component, int category, String message, int value)
      Logs a message and an integer value in the specified category for the specified component.
      static void log(Object component, int category, String message, Throwable e)
      Logs a message in the specified category for the specified component.
      static void log(Object component, int category, Throwable e)
      Logs a message in the specified category for the specified component.
      static void main(String[] args)
      Update trace parameters.
      void run()
      Listens for trace status changes.
      static void setFileName(Object component, String fileName)
      Sets the trace file name for the specified component.
      static void setFileName(String fileName)
      Sets the trace file name.
      static void setPrintWriter(Object component, PrintWriter obj)
      Sets the PrintWriter object for the specified component.
      static void setPrintWriter(PrintWriter obj)
      Sets the PrintWriter object.
      static void setTraceAllOn(boolean traceAll)
      Sets tracing for all categories on or off.
      static void setTraceConversionOn(boolean traceConversion)
      Sets character set conversion tracing on or off.
      static void setTraceDatastreamOn(boolean traceDatastream)
      Sets data stream tracing on or off.
      static void setTraceDiagnosticOn(boolean traceDiagnostic)
      Sets diagnostic tracing on or off.
      static void setTraceErrorOn(boolean traceError)
      Sets error tracing on or off.
      static void setTraceInformationOn(boolean traceInformation)
      Sets information tracing on or off.
      static void setTraceJDBCOn(boolean traceJDBC)
      Sets JDBC tracing on or off.
      static void setTraceOn(boolean traceOn)
      Sets tracing on or off.
      static void setTracePCMLOn(boolean tracePCML)
      Sets PCML tracing on or off.
      static void setTraceProxyOn(boolean traceProxy)
      Sets proxy stream tracing on or off.
      static void setTraceThreadOn(boolean traceThread)
      Sets thread tracing on or off.
      static void setTraceWarningOn(boolean traceWarning)
      Sets warning tracing on or off.
      static String toAsciiString(byte b)
      Returns a string representation of the byte argument, as 1 ascii digits.
      static String toEbcdicString(byte b)
      Returns a string representation of the byte argument, as 1 ebcdic digits.
      static String toHexString(byte b)
      Returns a string representation of the byte argument, as 2 hexadecimal digits.
      static String toHexString(byte[] bytes)
      Returns a string representation of the byte-array argument, as a sequence of hexadecimal digits.
    • Field Detail

      • DATASTREAM

        public static final int DATASTREAM
        'Data stream' trace category. This category is used by Toolbox classes to log data flow between the local host and the remote system. It is not intended for use by application classes.
        See Also:
        Constant Field Values
      • DIAGNOSTIC

        public static final int DIAGNOSTIC
        'Diagnostic message' trace category. This category is used to log object state information.
        See Also:
        Constant Field Values
      • ERROR

        public static final int ERROR
        'Error message' trace category. This category is used to log errors that cause an exception.
        See Also:
        Constant Field Values
      • INFORMATION

        public static final int INFORMATION
        'Information message' trace category. This category is used to track the flow of control through the code.
        See Also:
        Constant Field Values
      • WARNING

        public static final int WARNING
        'Warning message' trace category. This category is used to log errors that are recoverable.
        See Also:
        Constant Field Values
      • CONVERSION

        public static final int CONVERSION
        'Character set conversion' trace category. This category is used by Toolbox classes to log conversions between Unicode and native code pages. It is not intended for use by application classes.
        See Also:
        Constant Field Values
      • PROXY

        public static final int PROXY
        'Proxy' trace category. This category is used by Toolbox classes to log data flow between the client and the proxy server. It is not intended for use by application classes.
        See Also:
        Constant Field Values
      • PCML

        public static final int PCML
        'PCML' trace category. This category is used to determine how PCML interprets the data that is sent to and from the system.
        See Also:
        Constant Field Values
      • JDBC

        public static final int JDBC
        'JDBC' trace category. This category is used by the Toolbox JDBC driver to determine whether or not JDBC data should be included in the standard Toolbox trace. This setting is independent of what is set using the DriverManager class.
        See Also:
        Constant Field Values
      • LOGGER_NAME

        public static final String LOGGER_NAME
        Name of the instance of java.util.logging.Logger that the Toolbox uses. If no Logger by this name exists in the JVM, then traditional Toolbox tracing is done. To activate a Toolbox logger, the application can simply call Logger.getLogger(Trace.LOGGER_NAME).
        Note: This constant resolves to the value com.ibm.as400.access.
        See Also:
        Constant Field Values

    • Method Detail

      • getFileName

        public static String getFileName()
        Returns the trace file name.
        Returns:
        The file name if logging to file. If logging to System.out, null is returned.
      • getFileName

        public static String getFileName(Object component)
        Returns the trace file name for the specified component. Null is returned if no file name has been set for the component.
        Returns:
        The file name for the specified component. Null is returned if no file name has been set for the component.
      • getPrintWriter

        public static PrintWriter getPrintWriter()
        Returns the PrintWriter object.
        Returns:
        The PrintWriter object for the trace data output.
      • getPrintWriter

        public static PrintWriter getPrintWriter(Object component)
        Returns the print writer object for the specified component. Null is returned if no writer or file name has been set. If a file name for a component is set, that component automatically gets a print writer.
        Returns:
        The print writer object for the specified component. If no writer or file name has been set, null is returned.
      • isTraceAllOn

        public static final boolean isTraceAllOn()
        Indicates if all of the tracing categories are enabled.
        Returns:
        true if all categories are traced; false otherwise.
      • isTraceConversionOn

        public static final boolean isTraceConversionOn()
        Indicates if character set conversion tracing is enabled.
        Returns:
        true if conversions are traced; false otherwise.
      • isTraceDatastreamOn

        public static final boolean isTraceDatastreamOn()
        Indicates if data stream tracing is enabled.
        Returns:
        true if data streams are traced; false otherwise.
      • isTraceDiagnosticOn

        public static final boolean isTraceDiagnosticOn()
        Indicates if diagnostic tracing is enabled.
        Returns:
        true if diagnostic messages are traced; false otherwise.
      • isTraceErrorOn

        public static final boolean isTraceErrorOn()
        Indicates if error tracing is enabled.
        Returns:
        true if error messages are traced; false otherwise.
      • isTraceInformationOn

        public static final boolean isTraceInformationOn()
        Indicates if information tracing is enabled.
        Returns:
        true if information messages are traced; false otherwise.
      • isTraceJDBCOn

        public static final boolean isTraceJDBCOn()
        Indicates if JDBC tracing is enabled.
        Returns:
        true if JDBC messages are traced; false otherwise.
      • isTraceOn

        public static final boolean isTraceOn()
        Indicates if overall tracing is enabled. If this is false, no tracing occurs.
        Returns:
        true if tracing is enabled; false otherwise.
      • isTraceOn

        public static final boolean isTraceOn(int category)
        Indicates if tracing is enabled for the specified category.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        Returns:
        true if tracing for the category is enabled; false otherwise.
      • isTracePCMLOn

        public static final boolean isTracePCMLOn()
        Indicates if PCML tracing is enabled.
        Returns:
        true if PCML messages are traced; false otherwise.
      • isTraceProxyOn

        public static final boolean isTraceProxyOn()
        Indicates if proxy tracing is enabled.
        Returns:
        true if proxy tracing is enabled; false otherwise.
      • isTraceThreadOn

        public static final boolean isTraceThreadOn()
        Indicates if thread tracing is enabled.
        Returns:
        true if thread tracing is enabled; false otherwise.
      • isTraceWarningOn

        public static final boolean isTraceWarningOn()
        Indicates if warning tracing is enabled.
        Returns:
        true if warning messages are traced; false otherwise.
      • log

        public static final void log(int category,
               String message)
        Logs a message in the specified category. If the category is disabled, nothing is logged.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
      • log

        public static final void log(int category,
               Object source,
               String message)
        Logs a message in the specified category. If the category is disabled nothing is logged.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        source - Object that is posting this message.
      • log

        public static final void log(Object component,
               int category,
               String message)
        Logs a message for the specified component for the specified category. If the category is disabled, nothing is logged. If no print writer or file name has been set for the component, nothing is logged.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
      • log

        public static final void log(Object component,
               int category,
               Object source,
               String message)
        Logs a message for the specified component for the specified category. If the category is disabled, nothing is logged. If no print writer or file name has been set for the component, nothing is logged.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        source - The object posting this message.
      • log

        public static final void log(int category,
               String message,
               Throwable e)
        Logs a message in the specified category. If the category is disabled, nothing is logged.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        e - The Throwable object that contains the stack trace to log.
      • log

        public static final void log(int category,
               Object source,
               String message,
               Throwable e)
        Logs a message in the specified category. If the category is disabled, nothing is logged.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        e - The Throwable object that contains the stack trace to log.
        source - The object posting this message.
      • log

        public static final void log(Object component,
               int category,
               String message,
               Throwable e)
        Logs a message in the specified category for the specified component. If the category is disabled, nothing is logged.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        e - The Throwable object that contains the stack trace to log.
      • log

        public static final void log(int category,
               Throwable e)
        Logs a message in the specified category. If the category is disabled, nothing is logged.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        e - The Throwable object that contains the stack trace to log.
      • log

        public static final void log(Object component,
               int category,
               Throwable e)
        Logs a message in the specified category for the specified component. If the category is disabled, nothing is logged.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        e - The Throwable object that contains the stack trace to log.
      • log

        public static final void log(int category,
               String message,
               int value)
        Logs a message and an integer value in the specified category. If the category is disabled, nothing is logged. The integer value is appended to the end of the message, preceded by two blanks.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The integer value to log.
      • log

        public static final void log(int category,
               Object source,
               String message,
               int value)
        Logs a message and an integer value in the specified category. If the category is disabled, nothing is logged. The integer value is appended to the end of the message, preceded by two blanks.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The integer value to log.
        source - The object posting this message.
      • log

        public static final void log(int category,
               String message,
               String value)
        Logs a message and a String value in the specified category. If the category is disabled, nothing is logged. The String value is appended to the end of the message, preceded by two blanks.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The String value to log.
      • log

        public static final void log(Object component,
               int category,
               String message,
               int value)
        Logs a message and an integer value in the specified category for the specified component. If the category is disabled, nothing is logged. The integer value is appended to the end of the message, preceded by two blanks.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The integer value to log.
      • log

        public static final void log(int category,
               String message,
               boolean value)
        Logs a message and a boolean value in the specified category. If the category is disabled, nothing is logged. The boolean value is appended to the end of the message, preceded by two blanks. true is logged for true, and false is logged for false.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The boolean data to log.
      • log

        public static final void log(int category,
               Object source,
               String message,
               boolean value)
        Logs a message and a boolean value in the specified category. If the category is disabled, nothing is logged. The boolean value is appended to the end of the message, preceded by two blanks. true is logged for true, and false is logged for false.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The boolean data to log.
        source - The object posting this message.
      • log

        public static final void log(Object component,
               int category,
               String message,
               boolean value)
        Logs a message and a boolean value in the specified category for the specified component. If the category is disabled, nothing is logged. The boolean value is appended to the end of the message, preceded by two blanks. true is logged for true, and false is logged for false.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        value - The boolean data to log.
      • log

        public static final void log(int category,
               String message,
               byte[] data)
        Logs a message and byte data in the specified category. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        data - The bytes to log.
      • log

        public static final void log(int category,
               Object source,
               String message,
               byte[] data)
        Logs a message and byte data in the specified category. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        data - The bytes to log.
      • log

        public static final void log(Object component,
               int category,
               String message,
               byte[] data)
        Logs a message and byte data in the specified category for the specified component. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        data - The bytes to log.
      • log

        public static final void log(int category,
               String message,
               byte[] data,
               int offset,
               int length)
        Logs a message and byte data in the specified category. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
        Parameters:
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        data - The bytes to log.
        offset - The start offset in the data.
        length - The number of bytes of data to log.
      • log

        public static final void log(Object component,
               int category,
               String message,
               byte[] data,
               int offset,
               int length)
        Logs a message and byte data in the specified category for the specified component. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
        Parameters:
        component - The component to trace.
        category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
        message - The message to log.
        data - The bytes to log.
        offset - The start offset in the data.
        length - The number of bytes of data to log.
      • toHexString

        public static final String toHexString(byte b)
        Returns a string representation of the byte argument, as 2 hexadecimal digits.
        Parameters:
        b - A byte to be converted to a string.
        Returns:
        The 2-digit hexadecimal string representation of the byte argument.
      • toAsciiString

        public static final String toAsciiString(byte b)
        Returns a string representation of the byte argument, as 1 ascii digits.
        Parameters:
        b - A byte to be converted to a string.
        Returns:
        The 1-digit ascii string representation of the byte argument.
      • toEbcdicString

        public static final String toEbcdicString(byte b)
        Returns a string representation of the byte argument, as 1 ebcdic digits.
        Parameters:
        b - A byte to be converted to a string.
        Returns:
        The 1-digit ebcdic string representation of the byte argument.
      • toHexString

        public static final String toHexString(byte[] bytes)
        Returns a string representation of the byte-array argument, as a sequence of hexadecimal digits.
        Parameters:
        bytes - A byte array to be converted to a string.
        Returns:
        The hexadecimal string representation of the byte array argument.
      • setTraceAllOn

        public static void setTraceAllOn(boolean traceAll)
        Sets tracing for all categories on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceAll - If true, tracing for each category is on; otherwise, tracing for each category is off.
        See Also:
        setTraceOn(boolean)
      • setTraceConversionOn

        public static void setTraceConversionOn(boolean traceConversion)
        Sets character set conversion tracing on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceConversion - If true, conversion tracing is on; otherwise, conversion tracing is off.
        See Also:
        setTraceOn(boolean)
      • setTraceDatastreamOn

        public static void setTraceDatastreamOn(boolean traceDatastream)
        Sets data stream tracing on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceDatastream - If true, data stream tracing is on; otherwise, data stream tracing is off.
        See Also:
        setTraceOn(boolean)
      • setTraceDiagnosticOn

        public static void setTraceDiagnosticOn(boolean traceDiagnostic)
        Sets diagnostic tracing on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceDiagnostic - If true, diagnostic tracing is on; otherwise, diagnostic tracing is off.
        See Also:
        setTraceOn(boolean)
      • setTraceErrorOn

        public static void setTraceErrorOn(boolean traceError)
        Sets error tracing on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceError - If true, error tracing is on; otherwise, error tracing is off.
        See Also:
        setTraceOn(boolean)
      • setFileName

        public static void setFileName(String fileName)
                                throws IOException
        Sets the trace file name. All further trace output is sent to the file. If the file exists, output is appended to it. If the file does not exist, it is created.
        Parameters:
        fileName - The log file name. If this is null, output goes to System.out.
        Throws:
        IOException - If an error occurs while accessing the file.
        See Also:
        setPrintWriter(PrintWriter)
      • setFileName

        public static void setFileName(Object component,
                       String fileName)
                                throws IOException
        Sets the trace file name for the specified component. All further trace output for the specified component is sent to the file. If the file exists, output is appended to it. If the file does not exist, it is created.
        Parameters:
        fileName - The log file name. If this is null, output goes to System.out.
        component - The component to trace to the file.
        Throws:
        IOException - If an error occurs while accessing the file.
        See Also:
        setPrintWriter(Object,PrintWriter)
      • setPrintWriter

        public static void setPrintWriter(PrintWriter obj)
                                   throws IOException
        Sets the PrintWriter object. All further trace output is sent to the writer.
        Parameters:
        obj - The PrintWriter object. If this is null, output goes to System.out. Note: The PrintWriter class has no relationship with IBM i "printer devices".
        Throws:
        IOException - If an error occurs while accessing the file.
        See Also:
        setFileName(String)
      • setPrintWriter

        public static void setPrintWriter(Object component,
                          PrintWriter obj)
                                   throws IOException
        Sets the PrintWriter object for the specified component. All further trace output for the specified component is sent to the writer.
        Parameters:
        component - The component to trace to the writer.
        obj - The PrintWriter object. If this is null, output goes to System.out. Note: The PrintWriter class has no relationship with IBM i "printer devices".
        Throws:
        IOException - If an error occurs while accessing the file.
        See Also:
        setFileName(Object,String)
      • setTraceInformationOn

        public static void setTraceInformationOn(boolean traceInformation)
        Sets information tracing on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceInformation - If true, information tracing is on; otherwise, information tracing is off.
        See Also:
        setTraceOn(boolean)
      • setTraceJDBCOn

        public static void setTraceJDBCOn(boolean traceJDBC)
        Sets JDBC tracing on or off. The actual tracing does not happen unless tracing is on. If there is already a log writer or log stream registered with the DriverManager, then that one is used independent of the stream being used by this Toolbox Trace class. Replacing the log writer or log stream in use by the DriverManager after calling this method does not turn off this driver's JDBC tracing; it merely changes the destination of the output. In this way, it is possible to have JDBC trace data directed to 3 separate logging facilities: The stream used by this Trace class, the stream used by DriverManager.setLogStream(), and the writer used by DriverManager.setLogWriter().
        Parameters:
        traceJDBC - true to turn on JDBC tracing; false to turn it off.
        See Also:
        DriverManager
      • setTraceOn

        public static void setTraceOn(boolean traceOn)
        Sets tracing on or off. When this is off, nothing is logged in any category, even those that are on. When this is on, tracing occurs for all categories that are also on.
        Parameters:
        traceOn - If true, tracing is on; otherwise, all tracing is disabled.
      • setTracePCMLOn

        public static void setTracePCMLOn(boolean tracePCML)
        Sets PCML tracing on or off. The actual tracing does not happend unless tracing is on.
        Parameters:
        tracePCML - If true, PCML tracing is on; otherwise, PCML tracing is off.
      • setTraceProxyOn

        public static void setTraceProxyOn(boolean traceProxy)
        Sets proxy stream tracing on or off. The actual tracing does not happen unless tracing is on.
        Parameters:
        traceProxy - If true, proxy tracing is on; otherwise, proxy tracing is off.
        See Also:
        setTraceOn(boolean)
      • setTraceThreadOn

        public static void setTraceThreadOn(boolean traceThread)
        Sets thread tracing on or off. The actual tracing does not happen unless tracing is on.
        Note: "thread" is not a separate trace category. That is, simply calling setTraceThreadOn(true) by itself will not cause any trace messages to be generated. Rather, it will cause additional thread-related information to be included in trace messages generated for other trace categories, such as "diagnostic" and "information".
        Parameters:
        traceThread - If true, thread tracing is on; otherwise, thread tracing is off.
        See Also:
        setTraceOn(boolean)
      • setTraceWarningOn

        public static void setTraceWarningOn(boolean traceWarning)
        Sets warning tracing on or off. The actual tracing does not happen unless tracing is enabled.
        Parameters:
        traceWarning - If true, warning tracing is enabled; otherwise, warning tracing is disabled.
        See Also:
        setTraceOn(boolean)
      • run

        public void run()
        Listens for trace status changes.
        Specified by:
        run in interface Runnable
      • main

        public static void main(String[] args)
        Update trace parameters.
        Parameters:
        args -