Previous Next Table of Contents

2. How SQLkit_PG works.

The seven SQLkit_PG functions consist of simple wrappers around some of the key functions in libpq.a, the PostgreSQL C language interface. With one exception, they communication with a PostgreSQL database via passed parameters and return value as documented below. The one exception is the function ret_pg(), which, in addition to parameters and return value, uses a temporary file to store data records returned to FlagShip from a PostgreSQL database. Any temporary file created by ret_pg() will be written in the directory identified by the environment variable PG_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 test 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_pg(), including its complete path, is returned in the second parameter to ret_pg(). 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_pg(), 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_pg() 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_pg() is an integer indicating how many records, i.e., lines, are found in the temporary file. ret_pg() may return zero or -1, in which case no temporary file is written. -1 indicates an error. You should tail your PG_ERROR_LOG to see specifically what went wrong.

The temporary file should be processed and deleted as soon as possible once ret_pg() 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 the temporary file. It all happens in buffers. Isn't Unix/Linux clever!

The data fields of all the retrieved records identified by the select statement, i.e., parameter one of ret_pg(), 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 psql utility provided in the PostgreSQL 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 test program pgtest.prg.

Non-select SQL statements may be issued with the function exec_pg(). To protect the integrity of the database in a multi-user environment, you may wish to create a transaction block by surrounding calls to exec_pg() with calls to begin_pg() - end_pg() or begin_pg() - rback_pg(). end_pg() will commit the transaction while rback_pg() will abort or roll it back.


Previous Next Table of Contents