Generating Client-side ODBC Traces and Driver Debug Logs

Important: Tracing can over-run your entire disk, and will cause substantial drops in performance. It is vital that you disable tracing once any issues have been resolved.

The general principles of ODBC tracing and Driver debug logging are the same for all drivers and all platforms. There are some differences in specific implementations. Please follow the instructions relevant to your deployment.






Filename tokens, valid for all platforms

In iODBC 3.51.0 and later, and UDA Release 5.2 and later, there are some tokens that may be included in the target file names to make them more easily identified when prolonged tracing, or tracing of multiple connections and/or applications, is required:

Token Expands to
$T a timestamp in YYYYMMDD-hhmmss format
$H the home-directory of the user as whom the process is running
$P the process-id (pid) of the application which invokes the driver manager, allowing for per-process log-files
$U the user-id under which the process is currently running

These options are case-insensitive, so, for instance, $p has the same effect as $P.

Hence you can specify, for example: 

[ODBC]
Trace         = 1
TraceFile     = iodbc.$U.$p.$T.log
TraceAutoStop = 0
;TraceDLL      =
Debug         = 1
DebugFile     = openlink.$u.$P.$t.log


This would produce separate iODBC trace files and OpenLink driver debug logs with names based on the userid, timestamp, and processid of each connection made.

Note that these tokens have no effect on MDAC (Windows driver manager) trace files, but they do have effect on driver debug logs produced on Windows.

Windows

Controlling ODBC Tracing with the Microsoft ODBC Administrator

  1. Quit all ODBC client applications.
  2. Open your Data Sources (ODBC) control panel (often found in the Administrative Tools subfolder).
  3. Click the Tracing tab.
  4. Locate the Log File Path field.
  5. Use the Log File Path field to specify the complete location of the file to which you wish to write the trace, e.g., C:\Temp\odbc.trace.txt.
    • You may use the Browse button to locate or create the file, or specify it manually.
  6. If the ODBC client application(s) you need to trace will run as System or under any other user login than your own, click the Machine-Wide tracing for all user identities box. This option is often necessary, even though it doesn't seem like it should be.
  7. Click the Start Tracing Now button, and exit the Data Sources (ODBC) control panel.
  8. Reopen the ODBC client application.
  9. Recreate the error condition.
  10. Locate the file(s) indicated in the log file path on the tracing tab.
  11. DISABLE TRACING ON THE TRACING TAB. Failure to do this will leave the logs running, which can overflow your disk, and will have significant impact on performance.

Driver Debug logging on Windows

Controlling Driver Debug logging through the Client Configuration Utility

  1. Launch the OpenLink Client Configuration Utility, oplcfg32.exe.
  2. Click to the ODBC tab.
  3. Set a target for the Debug File to the full path to your chosen log target. Note: The filename tokens described above may be used for Driver Debug logging, but they will have no effect on MDAC Tracing. For example: 


    C:\Program Files\OpenLink\Lite32\mydebug.$t.log

  4. Recreate your error message or error condition.
  5. Locate your debug log.
  6. Return to the Registry Editor (regedit), and unset DebugFile. Failure to do this will leave the logs running, which can overflow your disk, and will have significant impact on performance.

Controlling Driver Debug logging through the Registry Editor

  1. Open a DOS or CMD window on your Windows client.
  2. Run the regedit command. For example: 


    C:\> regedit

  3. Expand the HKEY_LOCAL_MACHINE\Software\OpenLink Software menu items.
  4. Locate the folder for the driver you're using, and the ODBC subfolder within that.
  5. Locate the DebugFile parameter. It will appear on the right side of regedit.
  6. Set DebugFile to the full path to your chosen log target. Note: The filename tokens described above may be used for Driver Debug logging, but they will have no effect on MDAC Tracing. For example: 


    C:\Program Files\OpenLink\Lite32\mydebug.$t.log

  7. Recreate your error message or error condition.
  8. Locate your debug log.
  9. Return to the Registry Editor (regedit), and unset DebugFile. Failure to do this will leave the logs running, which can overflow your disk, and will have significant impact on performance.

Extra Driver Debug Logging for Single-Tier "Express" Edition ODBC Drivers, Single-Tier "Lite" Edition ODBC-to-JDBC Bridge, or Multi-Tier "Enterprise" Edition JDBC Bridge Agent on Windows

The Express Edition driver is a DBMS-specific bundling of our "Lite" Edition ODBC Driver for JDBC Data Sources (also known as ODBC-JDBC Bridge Driver) with a DBMS-specific Type 4 JDBC Driver. Sometimes, troubleshooting requires looking into the Java calls made by the ODBC-JDBC Bridge, and the responses from the JDBC Driver. Similar logging may be needed with our "Lite" Edition ODBC Driver for JDBC Data Sources, or our "Enterprise" Edition Bridge Agent for JDBC Data Sources. These calls are logged within the Driver or Agent Debug Log by setting an environment variable -- 

LOG_JAVA_CALLS = YES

When Java-level troubleshooting is complete, you can set LOG_JAVA_CALLS to NO, or just leave it as-is if you disable Driver and Agent Debug Logging. (The LOG_JAVA_CALLS setting has no effect when Driver and Agent Debug Logging are inactive.)

Mac OS X

ODBC Tracing on Mac OS X

ODBC tracing may be controlled through the Tracing Tab of the OpenLink ODBC Administrator.app --




The same settings may be adjusted by manually editing the relevant configuration file --

The following example shows the settings for continuous driver manager tracing to files on the active user's Desktop. 

[ODBC]
Trace         = 1
TraceAutoStop = 0
;TraceDLL      =
TraceFile     = ~/Desktop/sql.trace.$p.$t.log


Driver Debug logging on Mac OS X

Driver Debug logging may be controlled through the DSN configuration (different panes for different drivers). Similar to ODBC tracing, there is a checkbox for turning this log on and off, and a text-entry box by which to specify the target file.

The same settings may be adjusted by manually editing the relevant configuration file --

When set through a GUI-based Administrator DSN setup, debug logging is per-DSN. When manually set, debug logging may be per-DSN, or in the global [ODBC] stanza which applies to all DSNs.

The following example shows the settings for continuous driver debug logging, for all DSNs and all OpenLink? ODBC drivers, to files on the active user's Desktop. 

[ODBC]
Debug         = 1
DebugFile     = ~/Desktop/sql.debug.$p.$t.log


Extra Driver Debug Logging for Single-Tier "Express" Edition ODBC Drivers, Single-Tier "Lite" Edition ODBC-to-JDBC Bridge, or Multi-Tier "Enterprise" Edition JDBC Bridge Agent on Mac OS X

The Express Edition driver is a DBMS-specific bundling of our "Lite" Edition ODBC Driver for JDBC Data Sources (also known as ODBC-JDBC Bridge Driver) with a DBMS-specific Type 4 JDBC Driver. Sometimes, troubleshooting requires looking into the Java calls made by the ODBC-JDBC Bridge, and the responses from the JDBC Driver. Similar logging may be needed with our "Lite" Edition ODBC Driver for JDBC Data Sources, or our "Enterprise" Edition Bridge Agent for JDBC Data Sources. These calls are logged within the Driver or Agent Debug Log by setting an environment variable -- LOG_JAVA_CALLS -- to YES.

When Java-level troubleshooting is complete, you can unset the variable, set it to NO, or just leave it as-is if you disable Driver and Agent Debug Logging. (The LOG_JAVA_CALLS setting has no effect when Driver and Agent Debug Logging are inactive.)

Mojave (10.14), High Sierra (10.13), Sierra (10.12), El Capitan (10.11), Yosemite (10.10), Mavericks (10.9), Mountain Lion (10.8), or Lion (10.7)

As of Lion, these simple Terminal.app commands will do the job -- 

# to start including Java calls
launchctl setenv LOG_JAVA_CALLS YES

# to stop including Java calls
launchctl unsetenv LOG_JAVA_CALLS


Note that any active applications will not reflect the change; you have to quit and relaunch.

A reboot or user log out will unset variables set with these commands, and you'll need to re-set them afterward. Persistent settings can be made through a launchd.plist, as described elsewhere.


Lion (10.7), Snow Leopard (10.6), Leopard (10.5), Tiger (10.4), Panther (10.3), Jaguar (10.2), Puma (10.1), or Cheetah (10.0)

On Mac OS X 10.6 and earlier, this is best done by creating (or editing) a file called environment.plist in a (normally invisible) directory called .MacOSX, in the user's home directory. This method also works on Lion (10.7).

You can execute one of these commands in Terminal.app, to open the file for editing in TextEdit.app -- 

open -e /Users/ShortUsername/.MacOSX/environment.plist
open -e ~/.MacOSX/environment.plist




If the file already exists, just add these two lines to the main <dict> block -- 

        <key>LOG_JAVA_CALLS</key>
        <string>YES</string>




If you're creating a new file, make sure it contains this entire block -- 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" 
        "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>LOG_JAVA_CALLS</key>
        <string>YES</string>
</dict>
</plist>


Unix-like OS including Linux, Solaris, HP-UX, AIX, and others

ODBC Tracing on Unix-like OS

To create ODBC Traces for the iODBC Driver Manager and OpenLink ODBC Driver on Unix-like OS, edit the active odbc.ini file, typically specified by the $ODBCINI environment variable and found in the /bin/ subdirectory of your OpenLink installation, and add an [ODBC] section like the following -- 

[ODBC]
Trace         = 1
TraceFile     = <iodbc-trace-filename>
TraceAutoStop = 0
;TraceDLL      =

-- where iodbc-filename is the full path to the file where the iODBC Driver Manager trace should be written. Tracing can be disabled by commenting out these parameters with a semi-colon (;), or setting Trace = 0.

Driver Debug logging on Unix-like OS

To create OpenLink Driver Debug logs for, edit the active odbc.ini file, typically specified by the $ODBCINI environment variable and found in the /bin/ subdirectory of your OpenLink installation, and add an [ODBC] section like the following -- 

[ODBC]
Debug         = 1
DebugFile     = <driver-log-filename>

-- where iodbc-filename is the full path to the file where the Driver Debug log should be written. Tracing can be disabled by commenting out these parameters with a semi-colon (;), or (with the most recent driver builds) by setting Debug = 0.

Extra Driver Debug Logging for Single-Tier "Lite" Edition ODBC-to-JDBC Bridge or Multi-Tier "Enterprise" Edition JDBC Bridge Agent on Unix-like OS

Sometimes, troubleshooting requires looking into the Java calls made by our "Lite" Edition ODBC Driver for JDBC Data Sources, or our "Enterprise" Edition Bridge Agent for JDBC Data Sources, and the responses from the JDBC Driver. These calls are logged within the Driver or Agent Debug Log by setting an environment variable -- 

LOG_JAVA_CALLS = YES

When Java-level troubleshooting is complete, you can set LOG_JAVA_CALLS = NO, or just leave it as-is if you disable Driver and Agent Debug Logging. (The LOG_JAVA_CALLS setting has no effect when Driver and Agent Debug Logging are inactive.)


Related