DB2TraceManager class

The com.ibm.db2.jcc.DB2TraceManager class controls the global log writer.

The global log writer is driver-wide, and applies to all connections. The global log writer overrides any other JDBC log writers. In addition to starting the global log writer, the DB2TraceManager class provides the ability to suspend and resume tracing of any type of log writer. That is, the suspend and resume methods of the DB2TraceManager class apply to all current and future DriverManager log writers, DataSource log writers, or IBM® Data Server Driver for JDBC and SQLJ-only connection-level log writers.

DB2TraceManager methods

getTraceManager

Format:

static public DB2TraceManager getTraceManager()
  throws java.sql.SQLException

Gets an instance of the global log writer.

setLogWriter

Formats:

public abstract void setLogWriter(String traceDirectory, 
  String baseTraceFileName, int traceLevel)
  throws java.sql.SQLException
public abstract void setLogWriter(String traceFile, 
  boolean fileAppend, int traceLevel)
  throws java.sql.SQLException
public abstract void setLogWriter(java.io.PrintWriter logWriter, 
  int traceLevel)
  throws java.sql.SQLException

Enables a global trace. After setLogWriter is called, all calls for DataSource or Connection traces are discarded until DB2TraceManager.unsetLogWriter is called.

When setLogWriter is called, all future Connection or DataSource traces are redirected to a trace file or PrintWriter, depending on the form of setLogWriter that you use. If the global trace is suspended when setLogWriter is called, the specified settings take effect when the trace is resumed.

Parameter descriptions:

traceDirectory

Specifies a directory into which global trace information is written. This setting overrides the settings of the traceDirectory and logWriter properties for a DataSource or DriverManager connection.

When the form of setLogWriter with the traceDirectory parameter is used, the JDBC driver sets the traceFileAppend property to false when setLogWriter is called, which means that the existing log files are overwritten. Each JDBC driver connection is traced to a different file in the specified directory. The naming convention for the files in that directory depends on whether a non-null value is specified for baseTraceFileName:

If a null value is specified for baseTraceFileName, a connection is traced to a file named traceFile_global_n.
n is the nth JDBC driver connection.
If a non-null value is specified for baseTraceFileName, a connection is traced to a file named baseTraceFileName_global_n.
baseTraceFileName is the value of the baseTraceFileName parameter.

n is the nth JDBC driver connection.

baseTraceFileName

Specifies the stem for the names of the files into which global trace information is written. The combination of baseTraceFileName and traceDirectory determines the full path name for the global trace log files.

traceFileName

Specifies the file into which global trace information is written. This setting overrides the settings of the traceFile and logWriter properties for a DataSource or DriverManager connection.

When the form of setLogWriter with the traceFileName parameter is used, only one log file is written.

traceFileName can include a directory path.

logWriter

Specifies a character output stream to which all global log records are written.

This value overrides the logWriter property on a DataSource or DriverManager connection.

traceLevel

Specifies what to trace.

You can specify one or more of the following traces with the traceLevel parameter:

com.ibm.db2.jcc.DB2BaseDataSource.TRACE_NONE (X'00')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_CONNECTION_CALLS (X'01')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_STATEMENT_CALLS (X'02')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_RESULT_SET_CALLS (X'04')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_DRIVER_CONFIGURATION (X'10')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_CONNECTS (X'20')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_DRDA_FLOWS (X'40')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_RESULT_SET_META_DATA (X'80')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_PARAMETER_META_DATA (X'100')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_DIAGNOSTICS (X'200')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_SQLJ (X'400')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_XA_CALLS (IBM Data Server Driver for JDBC and SQLJ type 2 connectivity for Db2 on Linux®, UNIX, and Windows systems only) (X'800')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_META_CALLS (X'2000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_DATASOURCE_CALLS (X'4000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_LARGE_OBJECT_CALLS (X'8000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_T2ZOS (X'10000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_SYSTEM_MONITOR (X'20000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_TRACEPOINTS (X'40000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_SYSPLEX (X'80000')
com.ibm.db2.jcc.DB2BaseDataSource.TRACE_ALL (X'FFFFFFFF')

To specify more than one trace, use one of these techniques:

Use bitwise OR (|) operators with two or more trace values. For example, to trace DRDA flows and connection calls, specify this value for traceLevel:
```
TRACE_DRDA_FLOWS|TRACE_CONNECTION_CALLS
```
Use a bitwise complement (tilde (~)) operator with a trace value to specify all except a certain trace. For example, to trace everything except DRDA flows, specify this value for traceLevel:
```
 ~TRACE_DRDA_FLOWS
```

fileAppend

Specifies whether to append to or overwrite the file that is specified by the traceFile parameter. true means that the existing file is not overwritten.

unsetLogWriter

Format:

public abstract void unsetLogWriter()
  throws java.sql.SQLException

Disables the global log writer override for future connections.

suspendTrace

Format:

public void suspendTrace()
  throws java.sql.SQLException

Suspends all global, Connection-level, or DataSource-level traces for current and future connections. suspendTrace can be called when the global log writer is enabled or disabled.

resumeTrace

Format:

public void resumeTrace()
  throws java.sql.SQLException

Resumes all global, Connection-level, or DataSource-level traces for current and future connections. resumeTrace can be called when the global log writer is enabled or disabled. If the global log writer is disabled, resumeTrace resumes Connection-level or DataSource-level traces. If the global log writer is enabled, resumeTrace resumes the global trace.

getLogWriter

Format:

public abstract java.io.PrintWriter getLogWriter()
  throws java.sql.SQLException

Returns the PrintWriter for the global log writer, if it is set. Otherwise, getLogWriter returns null.

getTraceFile

Format:

public abstract String getTraceFile()
  throws java.sql.SQLException

Returns the name of the destination file for the global log writer, if it is set. Otherwise, getTraceFile returns null.

getTraceDirectory

Format:

public abstract String getTraceDirectory()
  throws java.sql.SQLException

Returns the name of the destination directory for global log writer files, if it is set. Otherwise, getTraceDirectory returns null.

getTraceLevel

Format:

public abstract int getTraceLevel()
  throws java.sql.SQLException

Returns the trace level for the global trace, if it is set. Otherwise, getTraceLevel returns -1 (TRACE_ALL).

getTraceFileAppend

Format:

public abstract boolean getTraceFileAppend()
  throws java.sql.SQLException

Returns true if the global trace records are appended to the trace file. Otherwise, getTraceFileAppend returns false.