Previous Next Table of Contents

1. Introduction

1.1 What is SQLkit_PG?

SQLkit_PG is an API consisting of seven functions that may be linked to a FlagShip program. These functions allow you to communicate with a PostgreSQL database from within a FlagShip program. For example, you may retrieve (select), update, append, or delete records. Transaction blocks may be created to protect the integrety of the database in a multi-user environment, and changes to the database may be committed or rolled back under the control of a FlagShip program.

1.2 Why use SQLkit_PG?

Although the FlagShip compiler includes a powerful and efficient database, there are many reasons why you may prefer to store your data external to FlagShip. For example, if you are porting a legacy application that previously used an SQL database, it may be easier to load the data into a PostgreSQL database and reuse the already tested SQL to access it rather than to convert the data and all queries to the FlagShip environment. You may also find it easier to access data from C or Perl programs if it is stored in a PostgreSQL database. Although it is not impossible to access FlagShip databases from C or other languages, the simple C API of PostgreSQL as well as its interactive psql utility provide great ease and flexibilty of access. Finally, manipulating multiple tables of a relational database using a high-level language such as SQL is often conceptually simpler than writing explicit loops as required in the Clipper/FlagShip environment.

Of course, there are tradeoffs to consider when using a high-level language such as SQL and an external database. A FlagShip program accessing data in a native FlagShip database will almost always outperform the corrisponding FlagShip program accessing data in an external database. Nevertheless, PostgreSQL performs very well when accessing even large data tables; and when used in conjunction with the FlagShip compiler, provides the programmer with a very potent database server as well as the tools to write efficient and attractive client applications.

1.3 What versions of FlagShip and PostgreSQL work?

SQLkit_PG version 1.00 was developed under FlagShip version 4.42 (ELF) and PostgreSQL version 6.2.

The object file SQLkit_PG.o provided in this package will work only with ELF version 4.4x of the FlagShip compiler on Linux. It may work with ELF versions of Postgres95 as early as version 1.08 running on Linux, although all version from 1.08 thru 6.2 have not been tested.

1.4 How is SQLkit_PG delivered?

The seven functions making up SQLkit_PG are encapsulated in an object file (SQLkit_PG.o). You must link this file along with the PostgreSQL libpq.a or libpq.so library to your FlagShip program.

The files making up SQLkit_PG are in a gzipped tar file called sqlkit_pg.tgz.

Copy sqlkit_pg.tgz into a directory on your system and xxtract the files with the command: tar -xvzf sqlkit_pg.tgz

1.5 Terms of Usage.

SQLkit_PG version 1.00 is available at no cost. It is copyright 1997 Thomas E. Griffin and comes with no warranty.

Source code for SQLkit_PG version 1.00 is not provided. If you think you need it, send email to griffin@ocme.ucsf.edu.

1.6 How to get started.

Make certain that you have an ELF version 4.4x of FlagShip and a recent ELF version of PostgreSQL installed and functioning on your Linux machine. Run a few of the examples provided with the PostgreSQL distribution to verify that you are able to create and query a database. Make certain your linker can find the library libpq.a or libpq.so. You may, for example, wish to create a symbolic link to them in /usr/lib, or even to move them into that directory.

Extract the files of the SQLkit_PG package on your system as described above. The files are:

README.xx

this document in ASCII, Postscript and html

SQLkit_PG.o

object file containing seven functions

pgtest.prg

a simple demo program

abc.sh

a script to create the ``abc'' database

mkabc.sql

sql statements executed by abc.sh

Make certain that the script abc.sh is executable. If not, run the command:

chmod +x abc.sh

Now run the command:

./abc.sh
to create the ``abc'' database. It consists of only one table called ``part''. Try connecting to it with the psql utility and take a look at the contents of this table with the command select * from part;

If you are unable to create this database or query it, you probably have permissions problems with your PostgreSQL installation. Make certain you are running as a user authorized to create a database, etc. Check the PostgreSQL documentation for details.

Once you are able to create and query the ``abc'' database, you should compile and run the pgtest program to verify that the SQLkit_PG functions are working. Using vi, emacs or your favorite editor, edit the two calls to FS_SET() in pgtest.prg to suit your system. PG_RETRIEVE_DIR should be a directory on your system where you have read/write permission. Make certain that you end the name of this directory with a slash. Temporary files consisting of tuples returned by select statements will be written in this directory. PG_ERROR_LOG will be your PostgreSQL error log. If errors are encountered, SQLkit_PG functions will append messages to it before returning -1 to your FlagShip program. Please make certain you put PG_ERROR_LOG someplace where you have read/write permission. Of course, calling FS_SET() is only one of the ways that these environment variables may be set. But they must exist for SQLkit_PG to function properly.

You should now be able to compile

FlagShip pgtest.prg SQLkit_PG.o -o pgtest -lpq 
and to run the test program.
./pgtest
Although simple and somewhat contrived, pgtest provides a realistic demonstration of using FlagShip to browse and update a PostgreSQL database.


Previous Next Table of Contents