Chapter 3. Loading pgtcl into an Application

Abstract

This chapter describes how to use pgtcl with your Tcl application. Before using pgtcl commands, you must load the libpgtcl library into your Tcl application. There are three approaches to doing this, but care must be taken because of the dependency on the PostgreSQL client library libpq.

This chapter also describes pgtclsh and pgwish, which are Tcl and Tcl/Tk shells built with pgtcl.

This chapter only applies to the pgtcl-ng implementation of pgtcl. For other implementations, check the included documentation.

3.1. Using the Tcl Package Command

You can use the Tcl package command to load the pgtcl library. This is the recommended approach, especially if you have multiple applications using pgtcl on your system. For this to work, you need the libpgtcl library and the pkgIndex.tcl package index file installed. If these files are installed properly, your application can use:

package require Pgtcl

to load the pgtcl library. Or, if your application requires a specific version:

package require Pgtcl 1.6

This is the preferred method for loading a package into a Tcl application, however it does require some installation setup. Specifically, the library and package index file must be installed into a subdirectory of the Tcl $auto_path or $tcl_pkgPath directories. A typical location for installation of this package might be: /usr/lib/tcl8.4/pgtcl1.6/ . (Note the subdirectory name (here pgtcl1.6), does not need to match the library name, and by convention includes only the two parts of the version. Tcl looks in all subdirectories of its package library directory to find packages.) Refer to the Tcl documentation on pkgMkIndex for more details.

In addition to installing the libpgtcl library, you must install the libpq library in a location where it will be found by the system shared library loader. Just installing libpq in the package directory along with libpgtcl will not work.

On Unix-like systems, either install the libpq library into a well-known system directory such as /usr/local/lib, or install it somewhere else. If you install it somewhere else, either modify the system loader configuration (typically using a command like ldconfig), or use the environment variable LD_LIBRARY_PATH to tell the system loader where to find it.

On some systems Unix-like systems, such as Linux, the path where libpq was found when building libpgtcl is stored in the libpgtcl library (as rpath). This lets the system find the library even if it isn't in a well-known system directory or pointed to by LD_LIBRARY_PATH. The other methods of finding the library still apply, if it is not in the stored location.

On Windows systems, install the libpq library into a directory named in the PATH environment variable. It will also work if the libpq library is installed in the same directory as the Tcl script interpreter tclsh.exe or wish.exe.

Another option for installing the libpq library is to place it in the pgtcl package directory, and use a modified package index file to load it. Here is a pkgIndex.tcl package index file for Windows systems which enables loading both libraries from the package directory. (This file is included in the Windows binary distribution, and in the source distribution as pkgIndex.tcl.win32.)

# Tcl package index file, version 1.1
# This is a modified package index file for Pgtcl on Windows. libpgtcl needs
# libpq, but libpq has to be found on PATH. So this modifies PATH before
# loading libpgtcl, then restores PATH after. This allows you to store
# both libpgtcl.dll and [b]libpq.dll in the package directory.

proc Pgtcl__load_with_path {dir} {
  global env
  set save_path $env(PATH)
  append env(PATH) ";$dir"
  load [file join $dir libpgtcl.dll]
  set env(PATH) $save_path
}
package ifneeded Pgtcl 1.6.0 [list Pgtcl__load_with_path $dir]