Chapter 3. Loading pgtcl into an Application
Prev		Next

Chapter 3. Loading pgtcl into an Application

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 2.1

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.5/pgtcl2.1/ . (Note the subdirectory name (here pgtcl2.1), 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.

3.1.1. "Package require" setup for Unix-like systems

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 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.

3.1.2. "Package require" setup for Windows

There are two possibilities for libpgtcl on Windows systems: one built with Borland C++ Builder (BCC), and one built with MinGW. These have different dependencies.

Note

Starting with pgtclng-1.8.0, only MinGW tools are being tested and used. Information about BCC-built versions is included for reference only.

On Windows systems, using the MinGW-built libpgtcl.dll, the entire EnterpriseDB PostgreSQL bin directory needs to be available and on the PATH, because there are multiple dependent libraries. Supplying access to libpq.dll is not sufficient. (If necessary, you can trim this down by removing the executables.)

On Windows systems, using the BCC-built libpgtcl.dll, install the blibpq.dll library into a directory named in the PATH environment variable. (Note that the version of libpq built with BCC is called "blibpq.dll".) It will also work if the blibpq.dll library is installed in the same directory as the Tcl script interpreter tclsh.exe or wish.exe. Note: It will not work to simply place blibpq.dll in the same directory as libpgtcl.dll, unless the trick below using pkgIndex.tcl is used. It must be found on the PATH.

Another option for installing the blibpq.dll 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 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.7.2 [list Pgtcl__load_with_path $dir]

Prev		Next
2.4. Building and Installing on MacOS 10	Home	3.2. Directly loading `libpgtcl`