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