Alternative new libpq interface.

Some people suggested it might be a good idea to define a new
interface, maybe call it libpq2. (Actually this would be a good time
to abandon pq = postquel in favour of libpg.a ).

I'll therefore put forward the following proposal as a possible
starting point. I'm not particularly committed to either this
proposal, my previous proposal, or perhaps Peter's proposal. A new
interface is probably the cleanest, but the current library probably
isn't all bad either.

My idea is that there should be a very low level interface that has a
minimum of bloat and features and caching and copying. This would be
especially nice for me writing an ODMG interface because the ODMG
interface would be needing to cache and copy things about so having
libpq doing it too is extra overhead. It could also form the basis of
a trivial re-implementation of the current libpq in terms of this
interface.

So the criteria I used for the low level interface is...

*) Future-Proof. In preference to a PGconnect routine with 6 different
arguments, you create an empty PGConnection, set various attributes
via setter functions and then call connect. That way it is future
proof against needing more arguments. Similar for execQuery.

*) Speed. Lean and mean. We can write a fancier interface on top of
this for people who want convenience over speed. At this point I
havn't attempted to design one. Thus the getValue routine (pg_value
below), is not null-terminated. The higher level interface can make
sure of that if needed. In any case some sorts of data may contain
nulls.

The main thing I dislike about the current interface is that it's not
low-level enough. It won't let me get around the features that I don't
want (like caching the entire result).

Ok guys, which way do you want me to go? Or will someone else come
up with something better?

/*
The Postgres Low-Level Interface
*/

typedef int PG_ErrorCode;
/* Just creates an empty connection object. Like C++ new() */
PG_Connection *pg_newConnection();
void pg_freeConnection(PG_Connection *con);
/* setter functions */
void pg_setDb(con);
void pg_setUserName(con);
void pg_setPassword(con);
/* Connect to the database. TRUE for success */
PG_Boolean pg_connect(con);
/* Find out the error code for what happened */
/* In the future there should be a unified error code system */
PG_ErrorCode pg_connect_error(PG_Connection * con);

/* Just creates an empty query object */
PGquery * pg_newQuery(PGConnection *con);
void pg_freeQuery(PGquery *q);
/* setter function */
void pg_setSQL(char *query);
/* Executes the query */
PG_Boolean pg_exec_sql(PGquery *q);

typedef int PG_NextStatus;
#define PG_NEXT_EOF 0 /* No more records */
#define PG_NEXT_OK 1 /* Returned a record */
#define PG_NEXT_ERROR -1 /* Error */

/* get the next record */
PG_NextStatus pg_next(PG_Connection *con);
/* did the last record returned mark the start of a new group? */
PG_Boolean pg_new_group(PG_query *q);

typedef int PG_Length;

/* Get the data from a field, specifying the field number and
returning the length of the data */
void *pg_value(PGquery *q, int field_num, PG_Length *len);
PG_Boolean pg_is_null(PGquery *q, int field_num);
/* If update/insert or delete, returns the number of rows affected */
int pg_num_rows_affected(PGquery *q);
/* Returns the oid of the last inserted object */
Oid pg_last_oid(PGquery *q);
/* Get the field name */
char *pg_field_name(PGquery *q, int field_num);
/* Get the field type */
Oid pg_field_type(PGquery *q, int field_num);
/* Find out the error code for what happened */
/* In the future there should be a unified error code system */
PG_ErrorCode pg_query_error(PGquery *q);

/* Get a meaningful Error message for a code */
char *pg_errorMessage(PG_ErrorCode);