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.