2. How SQLkit_JLT works.

Contents of this section

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