Logging and Environment Variables

This chapter describes some tools you can use to perform troubleshooting. It discusses the following topics:

Caution:

Enable logging only when you need to perform troubleshooting. You should not enable logging during normal operation, because it will dramatically slow down performance.

When using the SQL Gateway (as discussed in “Using the SQL Gateway with ODBC”), be sure to consult the documentation for the remote database to which you are connecting.

Enabling Logging for ODBC on Windows

On Windows, to enable logging for an ODBC data source, you generally use the ODBC Data Source Administrator screen (within the Windows Control Panel). To access this screen, open the Windows Control Panel, open the Administrative Tools subpanel, and then double-click Data Sources (ODBC). Or open the Windows Control Panel and then double-click ODBC Data Sources.

Then do the following:

To enable logging for the client driver, find the definition of the DSN that you want to log. Different kinds of DSN are on different tabs. Click the appropriate tab. Look for a check box labeled ODBC Log (or Log or variations) and select it.
To enable logging for the driver manager, click the Tracing tab and then click the Start Tracing Now button.
The Log File Path field determines the location of the trace file.

The details may vary depending on your version of Windows as well as the client driver that you use for this DSN.

Note:

The default location of the CacheODBC.log file varies depending on the version of Windows. For Windows Vista and higher, the log will be created in the Public folder under %PUBLIC%\Logs (default path C:\Users\Public\Logs). This folder is accessible by all users and allows just one location for the log to be created. For earlier versions, the log is under %WINDIR% (the C:\Windows or C:\WinNT folder, depending on your version of Windows).

You can change the name and location of the log file by setting the CACHEODBCTRACEFILE environment variable (see “InterSystems ODBC Environment Variables” later in this chapter).

Enabling Logging for ODBC on UNIX®

On UNIX®, enable logging for ODBC as follows:

To enable logging for the client driver, use the CACHEODBCTRACE environment variable (as described later in “InterSystems ODBC Environment Variables”). Also configure the ODBC initialization file.
To enable logging for the driver manager, set the Trace entry in the ODBC initialization file. In the same file, the TraceFile entry specifies the name of the log file to create. For information on the initialization file, see “Configuring the ODBC Initialization File.”

Tip:

If you enable logging but the log file is not updated, either you might not have privileges to write to the file or the client application may have loaded the SO before you enabled logging. In the latter case, stop and restart the client application to force it to reload the SO and get the logging flag.

InterSystems ODBC Environment Variables

This section describes the environment variables that control the InterSystems ODBC client driver. Typically you use these only for debugging or diagnostics.

CACHEODBCDEFTIMEOUT

This variable allows you to specify the duration of a timeout for a default login. Its value is in seconds.

CACHEODBCPID

This boolean variable enables the automatic appending of the process ID number to the log file name. A value of 1 enables appending and a value of 0 disables it. By default, appending is off.

With CACHEODBCPID enabled, if the base log file is CacheODBC.log and is in your current directory, then the process ID of 21933 generates a full log file name of CacheODBC.log.21933.

Both CACHEODBCPID and CACHEODBCTRACEFILE affect the file name. For example, on Windows if you use CACHEODBCTRACEFILE to set the base file name of the log file (for instance, to C:/home/mylogs/mylog.txt and enable CACHEODBCPID, then log file names will be of the form C:/home/mylogs/mylog.txt.21965.

CACHEODBCTRACE (UNIX® Only)

This boolean variable enables client driver logging. The default name for this file is CacheODBC.log. For more information on logging, see “Enabling Logging for ODBC on UNIX®” earlier in this chapter.

CACHEODBCTRACEFILE

This variable specifies the location and name of the log file. This can be useful for placing the log file in a unique directory or giving it a unique name. The default location of the log file is as follows:

For UNIX®, the log is generated in the current directory by default.
For Windows platforms previous to Vista, the default location for the log file is %SYSTEMROOT%. For Vista, the default location for the log file is %PUBLIC%\Logs\CacheODBC.log. This directory is accessible by all users and allows just one location for the log to be created.

CACHEODBCTRACETHREADS

This variable controls whether the log also includes threading information. If the variable is 1, threading information is included; if it is 0, threading information is not included.

It can be useful to enable this additional kind of logging, if you need to debug a threaded application. However, it adds many extra lines to the log for most ODBC applications.

Note:

Trace Files on Windows 2003

There are special requirements for setting up the trace file on Windows 2003, specifically for the situation where ODBC is being run by the Web server process. In addition to ensuring that the ODBC client has permission to write to the appropriate logging directory, you need to perform the following procedure:

Specify CACHEODBCTRACEFILE as C:\ODBC_Logs\CacheODBC.log.
When specifying the log file information, you also have the option of defining the CACHEODBCPID environment variable to include PID information. To do this, create another new variable with a name of CACHEODBCPID and a value of 1.
Create the directory C:\ODBC_Logs and grant universal write access to this directory.
Activate ODBC logging by selecting the ODBC Log check box in the DSN setup screen.