Generating Clientside ODBC Traces (All Drivers)

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.

Unix

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

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

Where iodbc-filename is the name of the file the iODBC Driver Manager trace should be written to and openlink-filename is the name of the file the OpenLink ODBC Driver trace should be written to. Tracing can be disabled by commenting out these parameters with a semi colon (;).

New filename tokens

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

• $P — This is the process-id (pid) of the application invoking the driver manager - allowing for per-process log-files
  
• $U — This is the user-id under which the process is currently running
  
• $T — This is the timestamp in YYYYMMDDHHmmSS format
  
• $H — This is the home-directory of the user as whom the process is running

Hence you can specify, for example:

[ODBC]
Trace         = 1
TraceFile     = iodbc-$U-$P-$T.log
DebugFile     = openlink-$U-$P-$T.log

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

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

Windows

The following documentation will allow you to produce an ODBC trace on Windows using the Microsoft ODBC Data Sources 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.
     
   • Consider using filename tokens in your file name to more easily identify particular files when tracing for a prolonged period, or tracing multiple connections or applications. See below.
     
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. Forward the file(s) to technical.support@openlinksw.com and reference your case.
    
12. DISABLE TRACING ON THE TRACING TAB.

Filename tokens

As of OpenLink ODBC Release 5.2, there are some new filename tokens that may be included in the target file names to make them more easily identified when prolonged tracing, or tracing of multiple connections or applications, is required:

• $P — This is the process-id (pid) of the application invoking the driver manager - allowing for per-process log-files
  
• $U — This is the user-id under which the process is currently running
  
• $T — This is the timestamp in YYYYMMDDHHmmSS format
  
• $H — This is the home-directory of the user as whom the process is running

Example usage: C:\SQL.$t.$p.log

Mac OS X

From the Tracing Tab of the OpenLink ODBC Administrator, the level of Tracing can be configured.

Figure: 1. OpenLink ODBC Administrator, Tracing tab

• When to trace — Use this option to turn tracing off or on. For a One-time only trace, the trace is made only for the duration of the next connection. Click the Apply button to make your selection active. This option corresponds to the Trace and TraceAutoStop parameters in the preference files.
  
• Custom trace library — Use the Select Library button to browse the machine for a library file that contains the code to intercept the trace output. This field should generally be left blank. When setting this parameter, you may use the Browse button to locate the library, or specify it manually. If specified manually, note that the location must be specified as it would be in a Terminal session. You may use ~/ as a shortcut to your user Home directory. This option corresponds to the TraceDLL parameter in the preference files.
  
• Log file path — Specify the complete location of the file to which you wish to write the trace. You may use the Browse button to locate or create the file, or specify it manually. If specified manually, note that the location must be specified as it would be in a Terminal session. You may use ~/ as a shortcut to your user Home directory. This option corresponds to the TraceFile parameter in the preference files.
  
• Trace Parameters in Preference Files — When the ODBC tracing parameters are changed, they are saved in the [ODBC] section of the ODBC.preference or odbc.ini file, whichever is active on your system.

The following example shows the settings for a one-time trace to a sql.log file on the active user's Desktop.

[ODBC]
Trace         = 1
TraceAutoStop = 1
;TraceDLL      =
TraceFile     = ~/Desktop/sql.log

• Trace — This parameter corresponds to the When to trace option in the Tracing tab. Set to 1, tracing is on; set to 0, tracing is off.
  
• TraceAutoStop — This parameter corresponds to the One-time only option in the tracing tab. Set to 1, tracing will automatically stop after the next connection is closed; set to 0, tracing must be manually stopped. When tracing is automatically stopped, the Trace and TraceAutoStop parameters will both be set to 0.
  
• TraceDLL — This parameter corresponds to the Custom trace library option in the tracing tab, and is very rarely used. When setting this parameter, note that the file must be fully specified as it would be in a Terminal session. You may use ~/ as a shortcut to your user Home directory.
  
• TraceFile — This parameter corresponds to the Log file path option in the tracing tab. When setting this parameter, note that the file must be fully specified as it would be in a Terminal session. You may use ~/ as a shortcut to your user Home directory.

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

• $P — This is the process-id (pid) of the application invoking the driver manager - allowing for per-process log-files
  
• $U — This is the user-id under which the process is currently running
  
• $T — This is the timestamp in YYYYMMDDHHmmSS format
  
• $H — This is the home-directory of the user as whom the process is running

These options are case-insensitive. Hence you can specify TraceFile = /tmp/iodbc-$U-$t-$P.log if you wish.