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.