1. Introduction

1.1 What is SQLkit_JLT?

SQLkit_JLT is an API consisting of eleven functions that may be linked to a FlagShip program. These functions allow you to communicate with a Just Logic database from within a FlagShip program. For example, you may retrieve (select), update, append, or delete records. Records may be locked or unlocked 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 What versions of FlagShip and Just Logic Database Manager work?

SQLkit_JLT version 0.98 was developed under FlagShip version 4.3 (a.out) and Just Logic Database Manager version 1.1 (a.out).

If you have not acquired and installed the client/server option from Just Logic, FlagShip programs using SQLkit_JLT must be run on the same machine running the Just Logic database server. Users running the FlagShip programs must have normal access to the Just Logic database.

If you have acquired and properly installed the Just Logic client/server option, SQLkit_JLT will allow FlagShip programs to communicate with a Just Logic database via sockets. The database may reside on a remote machine.

1.3 Is this production-quality software?

Yes, we think so. At the Office of Continuing Medical Education, University of California San Francisco, we have been using SQLkit_JLT on a Pentium 90 running Linux 1.2.9 (a.out) for six months. This system, which transacts approximately seven million dollars per year, replaced an aging MicroVAX running commercial Ingres. To date it has proven to be highly reliable and very cost effective.

1.4 How is SQLkit_JLT delivered?

The eleven functions making up SQLkit_JLT are encapsulated in two object files (fs_sql.o and fs_sqlnet.o). If you do not have the client/server option from Just Logic, or you do not wish to communicate via sockets, you would link your FlagShip program with fs_sql.o. If you have the client/server option and wish to communicate via sockets, perhaps to a remote database, link your FlagShip program with fs_sqlnet.o.

In addition, FlagShip source (sql_error.prg) for a twelfth function is provided as a simple example of how to trap an SQL error code returned by the database. Several demo programs are also included in the package as well as the README file that you are presently viewing.

These files are in a gzipped tar file called SQLkit_JLT0.98.tar.gz.

Create a directory on your system. Copy SQLkit_JLT0.98.tar.gz into it. Extract the files with the command: tar -xvzf SQLkit_JLT0.98.tar.gz

1.5 Terms of Usage.

SQLkit_JLT version 0.98 is available at no cost. It is copyright 1996 Thomas E. Griffin and comes with no warranty. A commercial product supporting FlagShip version 4.4 and ELF versions of the Just Logic Database Manager is under development.

Source code for SQLkit_JLT version 0.98 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 a.out version 4.3 of FlagShip and the a.out version of Just Logic installed and functioning on your Linux machine. Run the sample programs provided with the Just Logic distribution to create the ``abc'' database. Create a directory, say /home/fred/SQLkit, and extract the seven files of the SQLkit_JLT package in it as described above. The files are:

README: the file you are now reading
fs_sql.o: object file containing eleven functions; non-socket version
fs_sqlnet.o: object file containing eleven functions; socket version
sql_error.prg: FlagShip source to create sql_error.o
fstest.prg: a simple demo program
fstest1.prg: a more complex demo program
fstest2.prg: same as above, but uses sockets

Using vi, emacs or your favorite editor, edit sql_error.prg. Go to the line where FOPEN is called and edit the first parameter to be your error log. For example, you might change it to /home/fred/SQLkit/.jlt_error.log.

Run the command


FlagShip sql_error.prg -m -c

to create the object file sql_error.o.

You may now compile and run the first demo program (fstest.prg). But first edit fstest.prg, changing the last parameter of the FS_SET function call to your current working directory, say /home/fred/SQLkit/, or wherever you want the program to write its temporary files. Make certain you have read/write permission in this directory. The line should then look something like:


FS_SET("setenvir", "JLT_RETRIEVE_DIR", "/home/fred/SQLkit/")

Now compile the program


FlagShip fstest.prg fs_sql.o sql_error.o -o\ fstest -lsql

and run it


 ./fstest

If all goes well, the data in the parts table of the ``abc'' database will scroll across your screen. This isn't much of a program, but it proves that you have access to a Just Logic database from within a FlagShip program.

If there are problems, make sure that you can otherwise access the ``abc'' database, perhaps by using the sql utility provided by Just Logic:


sql
OK> connect database abc;
OK>select * from part;
 ... data should scroll here
OK> exit;

Also verify that you have read/write permission in the JLT_RETRIEVE_DIR defined in fstest.prg and to the error log opened near the bottom of sql_error.prg. Double check that FlagShip and the Just Logic Database Manager are properly installed on your machine.

If things are working for you, edit the location of JLT_RETRIEVE_DIR similarly in fstest1.prg, compile it as shown in the comments and run it:


 ./fstest1

Although still a simple program, fstest1 is a more realistic demonstration of using FlagShip to browse and update a Just Logic database.

Finally, if you have the client/server option from Just Logic, take a look at fstest2.prg. It is exactly the same program as fstest1 except that it uses sockets to communicate with the database. As you can see in the comments, fstest2.prg is linked against fs_sqlnet.o and libsqlnet.a ( i.e., -lsqlnet ). The environment variables JLT_DBMS_SERVER and JLT_DBMS_SERVER_CONFIG must be setup to conform to your system(s). Of course, there are various other ways to set these variables instead of calling FS_SET() as is done here.

Otherwise, the only difference between fstest1 and fstest2 is that open_jlt() requires three parameters, not just one, when using sockets, i.e., when linked against fs_sqlnet.o. The second parameter is the user's login name, and the third is her password. Be sure to change these parameters in fstest2.prg to those of a bonafide user on the machine running the sql server.

Next Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter