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