<!--

$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.8 2002/01/07 02:29:12 petere Exp $

$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.9 2002/03/04 18:50:20 momjian Exp $

-->

<chapter id="pgeasy">

<para>

Written by Bruce Momjian

(<email>pgman@candle.pha.pa.us</email>)

and last updated2000-03-30

and last updated2002-03-04

</para>

</note>

<para>

<application>pgeasy</application> allows you to cleanly interface

to the <application>libpq</application> library, more like a 4GL

SQL interface. Refer to <xref linkend="libpq"> for more

information about <application>libpq</application>

information about <application>libpq</application>.

</para>

<para>

It consists of set of simplified C functions that encapsulate the

functionality of <application>libpq</application>.

The functions are:

It consists of a set of simplified C functions that encapsulate the

functionality of <application>libpq</application>. The functions are:

<itemizedlist>

<listitem>

</synopsis>

</listitem>

<listitem>

<synopsis>

void unset_result(PGresult *oldres);

</synopsis>

</listitem>

</itemizedlist>

</para>

<para>

Many functions return a structure or value, so you cando morework

Many functions return a structure or value, so you can work

with the result if required.

</para>

<para>

You basically connect to the database with <function>connectdb</function>,

issue your query with <function>doquery</function>,

fetch the results with <function>fetch</function>,

and finish with <function>disconnectdb</function>.

You basically connect to the database with

<function>connectdb</function>, issue your query with

<function>doquery</function>, fetch the results with

<function>fetch</function>, and finish with

<function>disconnectdb</function>.

</para>

<para>

For <literal>SELECT</literal> queries, <function>fetch</function>

allows you to pass pointers as parameters, and on return the variables

are filled with data from the binary cursor you opened. These binary

cursors cannot be used if you are running the

<application>pgeasy</application>

client on a system with a different architecture than the database

server. If you pass a NULL pointer parameter, the column is skipped.

<function>fetchwithnulls</function> allows you to retrieve the NULL

status of the field by passing an <literal>int*</literal>

after each result pointer, which returns true or false if the field is null.

You can always use <application>libpq</application> functions on the <structname>PGresult</structname> pointer returned

by <function>doquery</function>.

<function>reset_fetch</function> starts the fetch back at the beginning.

allows you to pass pointers as parameters, and on return the

variables are filled with data from the binary cursor you opened.

These binary cursors cannot be used if you are running the

<application>pgeasy</application> client on a system with a different

architecture than the database server. If you pass a NULL pointer

parameter, the column is skipped. <function>fetchwithnulls</function>

allows you to retrieve the NULL status of the field by passing an

<literal>int*</literal> after each result pointer, which returns true

or false to indicate if the field is null. You can always use

<application>libpq</application> functions on the

<structname>PGresult</structname> pointer returned by

<function>doquery</function>. <function>reset_fetch</function> starts

the fetch back at the beginning.

</para>

<para>

<function>get_result</function>,

<function>unset_result</function>

allow youtohandle multiple result sets atthesame time.

<function>get_result</function> and <function>set_result</function>

variable. You can then later use<function>set_result</function> to

returnto thepreviously save result.

</para>

<para>

There are several demonstration programs in the

source directory.

There are several demonstration programs in

<filename>pgsql/src/interfaces/libpgeasy/examples</>.

</para>

</chapter>

CFLAGS=-I/usr/local/pgsql/include

TARGET = pginsert pgwordcount pgnulltest

TARGET = pginsert pgwordcount pgnulltest pgmultiresult

LDFLAGS = -L/usr/local/pgsql/lib -lpgeasy

all :$(TARGET)

pginsert:

gcc -o$@$(CFLAGS)$@.c$(PGEASY)$(LDFLAGS)

pgwordcount:

gcc -o$@$(CFLAGS)$@.c$(PGEASY)$(LDFLAGS)

pgnulltest:

%:%.c

gcc -o$@$(CFLAGS)$@.c$(PGEASY)$(LDFLAGS)

clean: