Note: these are the notes about version pre1 for pike/0.4. Differences
for version 0.5b4 and later of the Pike interpreter are at the bottom of
the file.

I don't have the time now to work on a BMML or HTML manual, so here's
a quick'n dirty one.
This module implements  the generic interface to databases as defined 
by Henrik Grubbstrom and myself.
There are a few noticeable differences, due to the peculiarities of
the postgres database. Unluckily, it can't be helped.

The programs in this connectivity systems are:
/precompiled/raw/sql/postgres
/precompiled/sql/postgres
/precompiled/sql/postgres_result

The first should not be used. Some functionalities are better offered
via a pike wrapper than by the atual connection tool, and those are implemented
by /precompiled/sql/postgres. You should also consider using the
generic SQL interface instead, as defined in /precompiled/sql

/precompiled/raw/sql/postgres has all that is needed to do queries, but lacks
all schema-related functions, since those muse be implemented via queries
to the system tables in the postgres database.
It implements the following functions (when nothing is specified,
it means they are interface-compilant):
- create : this is not exactly interface-compliant in that:
	-it ALWAYS has to bind to a database. In postgres connecting to a server
	 and to a database on that server are undistingushable operations.
	 It accepts four arguments as the default interface, 
	 plus a fifth optional argument which is the port number to connect to.
- select_db
- big_query : in Postgres there are different kind of errors
	(that means: different errors are reported differently by the frontend
	library). Those errors can be divided into three main categories: 
	fatal errors, nonfatal errors, no errors. This is reflected
	by the returned values of the function: a result object if there is a result
	to return, 0 if all went fine but there is no result to return, an exception
	if there has been an error fatal error, or 1 if there has been a nonfatal
	error (maybe this one should be reported via exceptions too?)
- error
- void reset() : tries to reset the connection to the database
- void set_notify_callback (int|function(string:void))
	Postgres supports asyncronous notification to clients.
	If this callback is set, it will be invoked when such a notification
	is received. Notice that notifications are carried piggy-back on
	query results. In the /precompiled/sql/posgres this function will
	allow a second argument, which will be the delay of a virtual cycle
	(implemented via call_out()s) of empty queries to the server, to
	allow such notifications to be delivered.
	Giving an integer argument resets the callback.

big_query() returns a clone of /precompiled/sql/postgres_result, which
implements:
- num_rows()
- num_fields()
- fetch_fields(): returns 0 or an array of mappings describing the fields.
- seek(n): seeks to the (current + n-th) row. n can be negative.
- fetch_row(): returns 0 or an array(mixed) with the data in the row.

Notice that postgres pads strings that shorter than the declared field
length with whitespaces (otherwise you have to use the varchar type).
This is incompatible with other servers, so I implemented a feature
that all trailing whitespaces in queries are cut. To change this behavior,
undefine CUT_TRAILING_SPACES in pgresult.c.

/precompiled/sql/postgres is a wrapper around the actual postgres
class, and handles all the schema-related parts of the interface,
as well as some high-level core functions. Its main difference over the
/precompiled/raw/sql/postgres is in the set_notify_callback function.
This one accepts a second (optional) integer argument. If given it
specifies the number of seconds to wait to poll the database.

************* CHANGES FOR VERSION 0.2pre1 ****************
Notice: I HAVEN'T TESTED IT YET!
0.1pre seemed to work, and the actual interface code hasn't changed.
I just adapted the interface to the pike counterpart and added arguments
typechecking.
The module system is still pretty much a mystery to me in its deepest
implications, and other modules (in particular Grubba's Mysql module) can
help me only so much, since my interface involves 3 pike programs and not
two. Furthermore, the three programs are not of the same 'type', since two
are C programs, the other one is a pike wrapper program. To sum it up, I might
have come up with a way to reference them all in a consistent way, or I
might have just failed miserably ;)
The three modules are referenced as "Sql.postgres", "Postgres.raw_postgres"
and "Sql.postgres_result" or "Postgres.postgres_result" (it should be the same,
really). Although the raw module _is_ in fact a complete module,
I strongly discourage you to use it.
To use them, you have to copy the files in the modules/Postgres/lib directory
by hand. postgres.h goes to the pike include dir 
(i.e. /usr/local/lib/pike/include)
while the files in the directory Sql.pmod go to the Sql.pmod subdirectory in
your pike modules directory (i.e. /usr/local/lib/pike/modules/Sql.pmod).
In the extras/ directory there are a couple example files.

********* VERSION 0.3 *****************
Adapts the interface to Pike/0.5beta6 and later.
Also cleaned up the installation process: now install only if postgres is
really supported

*********** VERSION 0.4 ***************
Changes in the create() interface: 
Postgres.postgres()->create() now accepts only 3 arguments (all optional):
-string hostname
-string database name
-int port
The interface compliancy is however guarranteed by Sql.postgres:
Sql.postgres()->create() accepts 4 arguments (instead of 5):
-string hostname
-string database name
-string user (ignored)
-string password (ignored)
the port number is encoded in the hostname, which now takes the form:
"hostname[:portnumber]"
