Previous Next Table of Contents

1. Introduction

1.1 What is SQLkit_sol?

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

1.2 Why use SQLkit_sol?

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 Solid 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 Solid database. Although it is not impossible to access FlagShip databases from C or other languages, Solid provides an industry standard C API as well as an interactive utility useful in this regard. Solid also provides a number of capabilities, such as logging, automatic backup, hot restart, etc., not available in FlagShip. 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, Solid performs extremely well when accessing even large data tables; and when used in conjunction with the FlagShip compiler, provides the developer 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 Solid work?

SQLkit_sol version 1.00 was developed under FlagShip version 4.4.

The object file SQLkit_sol.o provided in this package will work only with ELF version 4.4 of the FlagShip compiler on Linux. It requires an ELF versions of Solid.

1.4 How is SQLkit_sol delivered?

The seven functions making up SQLkit_sol are encapsulated in an object file (SQLkit_sol.o). You must link this file along with the Solid scllux22.a library and the standard math library ( -lm ) to your FlagShip program. See the comments in the sample program (soltest.prg) for details.

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

Create a directory on your system. Copy SQLkit_sol.tgz into it. Extract the files with the command: tar -xvzf SQLkit_sol.tgz

1.5 Terms of Usage.

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

Source code for SQLkit_sol 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 the ELF version 4.4 of FlagShip and the Solid Server installed and functioning on your Linux machine. Run a few of the examples provided with the Solid distribution to verify that you are able to create and query a database.

Then create a directory, say /home/fred/SQLkit, and extract the nine files of the SQLkit_sol package in it as described above. The files are:

README.txt

documentation in ASCII text

README.ps

documentation in PostScript

README.html

documentation in html

README-1.html

documentation in html

README-2.html

documentation in html

README-3.html

documentation in html

SQLkit_sol.o

object file containing seven functions

soltest.prg

a simple demo program

mkabc.sql

a script to create the ``abc'' database

Run the command:

solsql -f mkabc.sql
to create the ``abc'' database. It consists of only one table called ``part''. Try connecting to it with the solsql 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 some problem with your Solid installation. Make certain you are running as a user authorized to create a database, etc. Check the Solid documentation for details.

Once you are able to create and query the ``abc'' database, you should compile and run the soltest program to verify that the SQLkit_sol functions are working. Using vi, emacs or your favorite editor, edit the two calls to FS_SET() in soltest.prg to suit your system. SQL_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. SQL_ERROR_LOG will be your Solid/FlagShip error log. If errors are encountered, SQLkit_sol functions will append messages to it before returning -1 to your FlagShip program. Please make certain you put SQL_ERROR_LOG some place 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_sol to function properly. You should also decide if you wish to connect to the Solid Server via tcp or a pipe. Uncomment the appropriate call to open_sol() in soltest.prg. Please note that if you wish to communicate to Solid via a pipe you may need to change the permissions on the pipe created when Solid was installed on your system. (as root: chmod a+rw /tmp/solunp_SOLID/datapipe)

You should now be able to compile

FlagShip soltest.prg scllux22.a SQLkit_sol.o -o soltest -lm
and to run the test program.
./soltest
Although simple and somewhat contrived, soltest provides a realistic demonstration of using FlagShip to browse and update a Solid database.


Previous Next Table of Contents