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.