Loading pgtcl into an Application

PostgreSQL Tcl Interface Documentation
Prev | Fast Backward | Chapter 1. pgtcl - Tcl Binding Library | Fast Forward | Next

# 1.2. Loading pgtcl into an Application

Before using pgtcl commands, you must load the `libpgtcl` library into your Tcl application. This is normally done with the `package require` command. Here is an example:

    package require Pgtcl 1.5

`package require` loads the `libpgtcl` shared library, and loads any additional Tcl code that is part of the `Pgtcl` package. Note that you can manually generate the pkgIndex.tcl file, or use `make pkgIndex.tcl` or `make pkgIndex.tcl-hand` to have make generate it.

The old way to load the shared library is by using the Tcl `load` command. Here is an example:

    load libpgtcl[info sharedlibextension]

Although this way of loading the shared library is deprecated, we continue to document it for the time being, because it may help in debugging if, for some reason, `package require` is failing. The use of `info sharedlibextension` is recommended in preference to hard-wiring `.so` or `.sl` or `.dll` into the program.

The `load` command will fail unless the system's dynamic loader knows where to look for the `libpgtcl` shared library file. You may need to work with `ldconfig`, or set the environment variable `LD_LIBRARY_PATH`, or use some equivalent facility for your platform to make it work. Refer to the PostgreSQL installation instructions for more information.

`libpgtcl` in turn depends on the interface library `libpq`, so the dynamic loader must also be able to find the `libpq` shared library. In practice this is seldom an issue, since both of these shared libraries are normally stored in the same directory, but it can be a stumbling block in some configurations.

If you use a custom executable for your application, you might choose to statically bind `libpgtcl` into the executable and thereby avoid the `load` command and the potential problems of dynamic linking. See the source code for pgtclsh for an example.

If you want to use the `pg_sqlite` bridge, you must still explicitly `"package require sqlite3"` before executing any `sqlite3` commands.

Prev | Home | Next
pgtcl - Tcl Binding Library | Up | pgtcl Command Reference