With one exception, the functions provided in SQLkit_JLT permit
communication between a FlagShip program and a Just Logic database via
passed parameters and return value as documented below. The one
exception is the function sql_ret()
, which, in addition to
parameters and return value, uses a temporary file to store data
records returned to FlagShip from a Just Logic database. Any temporary
file created by sql_ret()
will be written in the directory
identified by the environment variable JLT_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 demo programs. 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 sql_ret()
, including
its complete path, is returned in the third parameter to
sql_ret()
. Please note that this is a pointer, so don't forget to
begin it with a ``@'' when you call the function. The fourth parameter
to sql_ret()
, 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 sql_ret()
is called. You should assign
the null string to parameter three and a zero to parameter four
immediately before calling the function. See the sample programs for
examples of this.
The actual return value of sql_ret()
is an integer indicating
how many records, i.e., lines, are found in the temporary
file. sql_ret()
may return zero or a negative number, in which
case no temporary file is written. A negative number should be
interpreted as a Just Logic error code (SQLCODE).
The temporary file should be processed and deleted as soon as possible
once sql_ret()
is called. 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 the temporary file. It all happens in
buffers. Isn't Unix/Linux clever!
All the fields of all the retrieved (selected) records 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 sql
utility provided in the Just Logic 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 demo programs fstest1.prg
and fstest2.prg
.
By default, all records retrieved (selected) by sql_ret()
or
sql_aret()
will be locked to other users. This remains true until
sql_commit()
is called by the locking program or the program
terminates. In addition, sql_ret()
and sql_aret()
will not
be able to retrieve (select) records already locked by another user.
If you do not wish to lock records or wish to retrieve (select)
records locked by other users, call sql_unlock()
before
sql_ret()
or sql_aret()
.
Next Chapter, Previous Chapter
Table of contents of this chapter, General table of contents
Top of the document, Beginning of this Chapter