Previous Next Table of Contents

2. How SQLkit_sol works.

The seven SQLkit_sol functions consist of simple wrappers around some of the key functions in the Solid C language interface. With one exception, they communication with a Solid database via passed parameters and return value as documented below.

The one exception is the function ret_sol(). In addition to parameters and return value, it uses a temporary file to store data records returned to FlagShip from a Solid database. Any temporary file created by ret_sol() will be written in the directory identified by the environment variable SQL_RETRIEVE_DIR. There are various ways you may set this environment variable. For example, in ~/.login, in ~/.profile, in ~/.bash_profile, or via the FS_SET() function as shown in the sample program. Please make certain that the content of this variable ends with a slash, e.g. /home/fred/SQLkit/, that the directory actually exists on your system, and that you have read/write permission in it.

The name of the temporary file created by ret_sol(), including its complete path, is returned in the second parameter to ret_sol(). Please note that this is a pointer, so don't forget to begin it with a ``@'' when you call the function. The third parameter to ret_sol(), also a pointer, will contain an integer indicating how many fields comprise each record in the temporary file. These two pointer parameters must be initialized in your FlagShip program to the proper data type before ret_sol() is called. You should assign the null string to parameter two and a zero to parameter three immediately before calling the function. See the sample program for an example of this.

The actual return value of ret_sol() is an integer indicating how many records, i.e., lines, are found in the temporary file. ret_sol() may return zero or -1, in which case no temporary file is written. -1 indicates an error. You should tail your SQL_ERROR_LOG to see specifically what went wrong.

The temporary file containing retrieved records should be processed and deleted as soon as possible once ret_sol() returns. If only a small amount of data is written to the temporary file, as is often the case, and little time passes between its creation and deletion, no actual disc activity will occur in connection with this file. It all happens in buffers. Isn't Unix/Linux clever!

The data fields of all retrieved records identified by the select statement, i.e., parameter one of ret_sol(), will be written in the temporary file. Each record consists of a single line, i.e., each record ends with the NEWLINE character. Each field ends with a bar. Null fields are empty and all data is returned as a character string in the same format as the solsql utility provided in the Solid distribution. A typical temporary file containing three records might look like this:

GRIFFIN, THOMAS|47|Programmer/Analyst|||19853|
BURKE, SARA||Director of CME||07/11/1982|14652|
JOHNSON, JANET||Office Manager||09/11/1989|18435|

Normally, the contents of a temporary file will be read into a two-dimensional array for further processing within the FlagShip program. Then the file will be deleted. An example of how to do this is provided in the sample program soltest.prg.

Non-select SQL statements may be issued with the function exec_sol(). To protect the integrity of the database in a multi-user environment, you must call commit_sol() or rb_sol() to commit or roll back any SQL statements that update your database.


Previous Next Table of Contents