NAME
	Postgres.postgres - Postgres (Postgres95, PgSQL) _RAW_ Server interface

AUTHOR
	Francesco Chemolli <kinkie@kame.usr.dsi.unimi.it>

DESCRIPTION
	This is an interface to the Postgres (Postgres95, pgsql) database server.
	This module may or may not be availible on your Pike, depending
	whether the appropriate include and library files 
	could be found at compile-time. Note that you DO NOT
	need to have a Postgres server running on your host to use this module:
	you can connect to the database over a TCP/IP socket

	Please notice that unless you wish to specifically connect to a Postgres
	server, you'd better use the Sql.sql program instead.
	I and Henrik Grubbström have (hopefully) designed a server-independent
	sql-server-class. The interfaces to all existing sql-classes
	are consistent. Using Sql.sql ensures that your Pike
	applications will run with any supported SQL server without changing
	a single line of code, at least for most common (and simple) operations.

	The program Postgres.postgres provides the _RAW_ interface
	to the database. Many functions are _NOT_ availible
	for this program. Therefore, its use is DEPRECATED.
	It is included in this documentation only for completeness' sake.
	Use Sql.postgres instead, or even better Sql.sql

SEE ALSO
	Sql.sql, Sql.postgres, Sql.postgres_result

============================================================================
NAME
	create - (re)inititalize connection and select database

SYNTAX
	object Postgres.postgres ();
	or
	object Postgres.postgres (string host, void|string database, void|int port);

DESCRIPTION
	With no arguments, this function initializes (reinitializes if a connection
	had been previously set up) a connection to the Postgres backend.
	Since Postgres requires a database to be selected, it will try
	to connect to the default database. The connection may fail however for a 
	variety of reasons, in this case the most likely of all is because
	you don't have enough authority to connect to that database.
	So use of this particular syntax is discouraged.

	The host argument allows you to connect to databases residing on different
	hosts. If it is 0 or "", it will try to connect to localhost.

	The database argument specifies the database to connect to. If 0 or "", it
	will try to connect to the default database.

NOTA BENE
	You need to have a database selected before using the sql-object, 
	otherwise you'll get exceptions when you try to query it.
	Also notice that this function CAN raise exceptions if the db
	server doesn't respond, if the database doesn't exist or is not accessible
	by you.

	You don't need bothering about syncronizing the connection to the database:
	it is automatically closed (and the database is sync-ed) when the
	object is destroyed.

SEE ALSO
	Sql.postgres, Sql.sql, postgres->select_db

============================================================================
NAME
	select_db - connect to a database

SYNTAX
	void select_db (string dbname);

DESCRIPTION
	This function allows you to connect to a database. Due to restrictions
	of the Postgres frontend-backend protocol, you always have to be connected
	to a database, so in fact this function just allows you to connect
	to a different database on the same server.

NOTA BENE
	This function CAN raise exceptions if something goes wrong (backend process
	not running, not enough permissions..)

SEE ALSO
	postgres->create

============================================================================
NAME
	big_query - Query the database

SYNTAX
	object (Sql.postgres_result) big_query (string sqlquery);

DESCRIPTION
	This is the only provided interface which allows you to query the
	database. If you wish to use the simpler "query" function, you need to
	use the Sql.sql generic sql-object.

	It returns a postgres_result object (which conforms to the Sql.sql_result
	standard interface for accessing data). I recommend using query() for
	simpler queries (because it is easier to handle, but stores all the result
	in memory), and big_query for queries you expect to return huge amounts
	of data (it's harder to handle, but fectches results on demand).

NOTA BENE
	This function _CAN_ raise exceptions. 

	The program Sql.postgres_result is exactly 
	the same as Postgres.postgres_result.

SEE ALSO
	Sql.sql, Sql.sql_result

============================================================================
NAME
	error - tell what the last server error was.

SYNTAX
	string error();

DESCRIPTION
	This function returns the textual description of the last server-related
	error. Returns 0 if no error has occurred yet. It is not cleared upon
	reading (can be invoked multiple times, will return the same result
	until a new error occurs).

SEE ALSO
	postgres->big_query

============================================================================
NAME
	host_info - describe the connection we're using

SYNTAX
	string host_info();

DESCRIPTION
 	This function returns a string describing what host are we talking to,
 	and how (TCP/IP or UNIX sockets).

============================================================================
NAME
	reset - resets a connection

SYNTAX
	void reset();

DESCRIPTION
	This function resets the connection to the backend. Can be used for
	a variety of reasons, for example to detect the status of a connection.

NOTA BENE
	This function is Postgres-specific, and thus it is not availible
	through the generic SQL-interface.

============================================================================
NAME
	_set_notify_callback - sets a notification callback for SQL events

SYNTAX
	void _set_notify_callback ();
	or
	void _set_notify_callback (function f);

DESCRIPTION
	With Postgres you can associate events and notifications to tables.
	This function allows you to detect and handle such events.

	With no arguments, resets and removes any callback you might have
	put previously, and any polling cycle.

	With one argument, sets the notification callback (there can be only
	one for each sqlobject). 
	
	The callback function must return no value, and takes a string argument,
	which will be the name of the table on which the notification event
	has occured. In future versions, support for user-specified arguments
	will be added.
	
NOTA BENE
	The Sql.postgres program adds support for automatic delivery of
	messages (see it for explanation on the inner workings of this feature.

	This function is Postgres-specific, and thus it is not availible
	through the generic SQL-interface.

SEE ALSO
	Sql.postgres

============================================================================
NAME
	version - show the version of the Postgres driver.

SYNTAX
	string Postgres.version;

DESCRIPTION
	Should you need to report a bug to the author, please submit along with
	the report the driver version number, as returned by this call.

============================================================================
EXTERNAL INFLUENCES on the module.
	These ones do not depend on my implementation really, they're just part
	of the Postgres C API. They take the form of certain environment variables
	which, if defined in the environment of the pike interpreter, influence
	the interface's behavior. 

	PGHOST: sets the name of the default host to connect to. It defaults
		to "localhost"
	
	PGOPTIONS: sets some extra flags for the frontend-backend connection.
	  DO NOT SET unless you're sure of what you're doing.
	
	PGPORT: sets the default port to connect to, otherwise it will use
	  compile-time defaults (that is: the time you compiled the postgres
		library, not the Pike driver).

	PGTTY: sets the file to be used for Postgres frontend debugging.
	  Do not use, unless you're sure of what you're doing.

	PGDATABASE: sets the default database to connect to.

	PGREALM: sets the default realm for Kerberos authentication. I never used
		this, so I can't help you.

	Refer to the Postgres documentation for further details.

NOTES
	I didn't make any testsuite for this module, since to test anything it would
	require a working Postgres server, and I can't make any assumption
	on those... You can try to use the included scripts (they're in the
	"pike/src/modules/Postgres/extras" directory
	but you'll probably have to patch them to reflect your site's settings.

	Also note that THIS MODULE USES BLOCKING I/O to connect to the server.
	Postgres is quite slow, and so you might want to consider this
	particular aspect. It is (at least should be) thread-safe, and so it can be used
	in a multithread environment.

THANKS
	Many thanks to Henrik Grubbström, without whose help this piece of
	code couldn't be nearly as complete as it is.
	Also thanks to Frederik Hubinette, for designing such a nice language
	as Pike.

COPYRIGHT
	This code and documentation are copyright 1997 Francesco Chemolli 
	<kinkie@kame.usr.dsi.unimi.it>.
	It may be copied, modified, redistributed under the terms of the
	GNU General Public License, version 2.
	
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with the Pike source. If not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

	The Pike programming language is copyright Frederik Hubinette, and is
	distributed under the terms of the GNU General Public License. For furhter
	information, please consult the Pike WWW site, at http://pike.idonex.se/
